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

  1. Ask for permission with messages.sendCallPermissionRequest and check it with getPermission.
  2. Business-initiated: connect with your SDP offer. User-initiated: receive the call webhook, then preAccept (optional) and accept with your SDP answer.
  3. End with terminate, or reject an 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

ParameterTypeDescription
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_hoursobjectstatus, timezone_id, weekly_operating_hours and an optional holiday_schedule.
callback_permission_status"ENABLED" | "DISABLED"Whether users can be asked for callback permission.
sipobjectSIP status and servers (hostname, port, request_uri_user_params, sip_user_password).