# Calling

URL: https://wa.genuka.com/sdk/calling
Language: English

> 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`.

```ts
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.

```ts
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.

| 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

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=…`.

```ts
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.
