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.
| Concern | Module | Genuka WA route |
|---|---|---|
| Calling settings of a number | calling/settings.ts | GET/PATCH /api/v1/numbers/{id}/calling |
| Call actions, with the SDP | calling/actions.ts | POST /api/v1/calls |
| Call permission of a user | calling/permissions.ts | GET /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
statuscannot wipe business hours. - SIP is read-only.
sipEnabledsays whether Meta sends call setup to a SIP server instead of the webhooks. Writes never carry thesipblock: 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.
validateCallingSettingsreturns every problem at once. Times areHHMM, 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.
| Action | Needs | What it does |
|---|---|---|
connect | to, sdp (offer) | Starts a call to a user who gave permission. Returns the call id. Omit sdp only with SIP signaling. |
pre_accept | callId, sdp (answer) | Sends your answer early so media starts while the agent picks up. Optional. |
accept | callId, sdp (answer) | Answers a user-initiated call. |
reject | callId | Declines a user-initiated call. |
terminate | callId | Hangs up an ongoing call. |
bizOpaqueCallbackData (connect and accept, at most 512 characters) comes back on that call's
webhooks.
A user calls you
- The
callswebhook brings the call id and the user's SDP offer. - Your stack builds the SDP answer. Send
pre_acceptwith it as soon as it exists. - When the agent is ready, send
acceptwith the same answer. terminateto 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
- Check
getCallPermission(...).canCall. Without it, send acall_permission_requestmessage and wait for the reply. connectwith your SDP offer. Keep the returned call id.- The user's SDP answer arrives on the
callswebhook.
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: [...] }statusis Meta's own:no_permission,temporary(about 7 days) orpermanent.canCallandcanRequestPermissionsay what you can do now. Asking is rate-limited per user per day and per week: no permission withcanRequestPermission: falsemeans wait, not ask again.actions[].limitssay when each limit resets.