Genuka WA docs

Calling

WhatsApp voice calls with webhook signaling: calling settings, call actions with SDP, call permissions.

WhatsApp voice calls, for a voice agent or any WebRTC stack you run yourself. Import from @genuka/whatsapp/calling.

import { MetaTransport } from "@genuka/whatsapp";
import { callAction, getCallPermission } from "@genuka/whatsapp/calling";

const transport = new MetaTransport({ accessToken });
const permission = await getCallPermission(transport, phoneNumberId, "237699001122");
if (permission.canCall) {
  const { callId } = await callAction(transport, phoneNumberId, {
    action: "connect",
    to: "237699001122",
    sdp: offer, // your WebRTC stack's SDP offer
  });
}

The audio never goes through this package, nor through Genuka WA. The SDP describes where it flows, between Meta and your own stack; these functions only carry it.

ConcernModuleGenuka WA route
Calling settings of a numbercalling/settings.tsGET/PATCH /api/v1/numbers/{id}/calling
Call actions, with the SDPcalling/actions.tsPOST /api/v1/calls
Call permission of a usercalling/permissions.tsGET /api/v1/calls/permissions

On Genuka WA, calling is included from the Growth plan.


Settings

GET/POST /{PHONE_NUMBER_ID}/settings, calling block.

const current = await getCallingSettings(transport, phoneNumberId);
const next = mergeCallingSettings(current, {
  status: "ENABLED",
  callHours: {
    status: "ENABLED",
    timezoneId: "Africa/Douala",
    weeklyOperatingHours: [{ dayOfWeek: "MONDAY", openTime: "0800", closeTime: "1800" }],
    holidaySchedule: [],
  },
});
await updateCallingSettings(transport, phoneNumberId, next);
  • Read, merge, write. A write always sends the complete block, so an update to status cannot wipe business hours.
  • SIP is read-only. sipEnabled says whether Meta sends call setup to a SIP server instead of the webhooks. Writes never carry the sip block: Meta redacts its password on read, and echoing it back breaks a working SIP setup.
  • Enabled is not callable. Meta still checks eligibility (messaging tier, country, a number shared with the WhatsApp Business app) and answers with its own error.
  • validateCallingSettings returns every problem at once. Times are HHMM, 24-hour, in the schedule's time zone. Slots on the same day must not overlap.

Call actions

POST /{PHONE_NUMBER_ID}/calls. The SDP type follows from the action, so you pass the SDP alone.

ActionNeedsWhat it does
connectto, sdp (offer)Starts a call to a user who gave permission. Returns the call id. Omit sdp only with SIP signaling.
pre_acceptcallId, sdp (answer)Sends your answer early so media starts while the agent picks up. Optional.
acceptcallId, sdp (answer)Answers a user-initiated call.
rejectcallIdDeclines a user-initiated call.
terminatecallIdHangs up an ongoing call.

bizOpaqueCallbackData (connect and accept, at most 512 characters) comes back on that call's webhooks.

A user calls you

  1. The calls webhook brings the call id and the user's SDP offer.
  2. Your stack builds the SDP answer. Send pre_accept with it as soon as it exists.
  3. When the agent is ready, send accept with the same answer.
  4. terminate to hang up. The webhook reports the end either way.

A user-initiated call rings for about 30 seconds (limits.CALLING.answerWindowSeconds). The whole round trip, from the webhook landing to pre_accept, has to fit in it.

You call a user

  1. Check getCallPermission(...).canCall. Without it, send a call_permission_request message and wait for the reply.
  2. connect with your SDP offer. Keep the returned call id.
  3. The user's SDP answer arrives on the calls webhook.

Permissions

GET /{PHONE_NUMBER_ID}/call_permissions?user_wa_id=….

const permission = await getCallPermission(transport, phoneNumberId, waId);
// { status: "temporary", expiresAt, canCall: true, canRequestPermission: false, actions: [...] }
  • status is Meta's own: no_permission, temporary (about 7 days) or permanent.
  • canCall and canRequestPermission say what you can do now. Asking is rate-limited per user per day and per week: no permission with canRequestPermission: false means wait, not ask again. actions[].limits say when each limit resets.

On this page