API reference · new in 1.1.0
whatsapp.calls
Drive the WhatsApp Business Calling API: start and answer calls, check whether you may call a user, and manage calling settings.
WebRTC is your responsibility. This module only drives Meta's signalling endpoints: you create the SDP offer/answer and carry the media yourself. Every method resolves to the usual { data, error } result.
Call flow
- Ask for permission with
messages.sendCallPermissionRequestand check it withgetPermission. - Business-initiated:
connectwith your SDP offer. User-initiated: receive thecallwebhook, thenpreAccept(optional) andacceptwith your SDP answer. - End with
terminate, orrejectan inbound call. You do not need to terminate when the user hangs up.
getPermission
whatsapp.calls.getPermission(user: string, opts?: { phoneNumberId?: string }): Promise<WhatsappResponse<CallPermissionState>>
Looks up whether you may call a user and your remaining permission-request and call limits. Pass a wa_id or a BSUID.
const { data, error } = await whatsapp.calls.getPermission("15551234567");
if (data?.permission.status !== "no_permission") {
const start = data?.actions.find((a) => a.action_name === "start_call");
console.log("Can start call:", start?.can_perform_action);
}connect (business-initiated call)
whatsapp.calls.connect(to: string, session: { sdp: string; sdpType?: "offer" }, opts?: { phoneNumberId?: string; bizOpaqueCallbackData?: string })
Starts a call. The user must have granted call permission first. to accepts a phone number or a BSUID.
const { data, error } = await whatsapp.calls.connect("15551234567", {
sdp: offerSdp, // from your WebRTC stack
});
console.log("Call ID:", data?.calls[0].id);preAccept, accept, reject, terminate
whatsapp.calls.preAccept(callId: string, session: CallSession, opts?)
whatsapp.calls.accept(callId: string, session: CallSession, opts?: { phoneNumberId?: string; bizOpaqueCallbackData?: string })
whatsapp.calls.reject(callId: string, opts?)
whatsapp.calls.terminate(callId: string, opts?)
preAccept is optional and prepares the media connection before you accept. Start sending media only after accept resolves successfully.
inbound-call.ts
whatsapp.webhooks.on("call", async (call) => {
if (call.event !== "connect" || !call.session) return;
const answerSdp = await createAnswer(call.session.sdp); // your WebRTC code
await whatsapp.calls.preAccept(call.callId, { sdpType: "answer", sdp: answerSdp });
const { error } = await whatsapp.calls.accept(call.callId, {
sdpType: "answer",
sdp: answerSdp,
});
if (error) await whatsapp.calls.reject(call.callId);
});
// Later, end the call from your side
await whatsapp.calls.terminate("wacid.HBgLM...");getSettings & updateSettings
whatsapp.calls.getSettings(opts?: { phoneNumberId?: string; includeSipCredentials?: boolean }): Promise<WhatsappResponse<CallingSettings>>
whatsapp.calls.updateSettings(settings: CallingSettings, opts?): Promise<WhatsappResponse<{ success: boolean }>>
Read or change the calling configuration of the phone number. Changes can take up to 7 days to reach all WhatsApp clients.
await whatsapp.calls.updateSettings({
status: "ENABLED",
call_icon_visibility: "DEFAULT",
callback_permission_status: "ENABLED",
call_hours: {
status: "ENABLED",
timezone_id: "Asia/Kolkata",
weekly_operating_hours: [
{ day_of_week: "MONDAY", open_time: "0900", close_time: "1800" },
],
},
});
const { data: settings } = await whatsapp.calls.getSettings();CallingSettings
| Parameter | Type | Description |
|---|---|---|
| status | "ENABLED" | "DISABLED" | Turns calling on or off for the phone number. |
| call_icon_visibility | "DEFAULT" | "DISABLE_ALL" | Controls whether the call icon is shown in the chat. |
| call_hours | object | status, timezone_id, weekly_operating_hours and an optional holiday_schedule. |
| callback_permission_status | "ENABLED" | "DISABLED" | Whether users can be asked for callback permission. |
| sip | object | SIP status and servers (hostname, port, request_uri_user_params, sip_user_password). |