POST/v1/whatsapp/calls

WhatsApp Calling

Initiate WhatsApp Call

The WhatsApp counterpart to Initiate Call. Rings the customer on WhatsApp from one of your connected WhatsApp Business numbers and connects them to an assistant, passing customer_name and additional_data through to it. WhatsApp only rings people who have allowed calls from your number — when the customer has not, a call permission request is sent to them instead and the response is 202.

Request

Endpoint

POST/v1/whatsapp/calls

Authentication

x-api-keyorAuthorization: Bearer

Body Parameters

Name	Type	Description
`customer_number`required	string \| number	The customer's WhatsApp number. Include the country code, or send a national number with customer_country_code — a number with neither is treated as being in the same country as your WhatsApp number.
`customer_name`required	string	Customer's name — the assistant uses it to address them. 1 to 200 characters.
`whatsapp_number`	string \| number	The connected WhatsApp Business number to call from. Matched on digits, so "+91 80000 12345" and "918000012345" are the same. Provide this or whatsapp_account_id.
`whatsapp_account_id`	ObjectId	Alternative to whatsapp_number — the id returned by List WhatsApp Numbers.
`assistant_id`	ObjectId	Assistant that speaks on this call. Defaults to the assistant assigned to the WhatsApp number. Must belong to your account.
`customer_country_code`	string	Customer's country calling code, digits only with an optional leading + (e.g. "+91"), when customer_number is a national number.
`additional_data`	object	Arbitrary context passed through to the assistant and stored on the call record (e.g. order_id, plan).
`request_permission`	boolean	Send the call permission request when the customer has not allowed calls yet. Defaults to true. Set false to get a 409 instead.
`template_name`	string	Call permission template to send, overriding the one chosen for the number. Must be approved by Meta.
`template_language`	string	Language code of template_name. Defaults to the number's template language, or "en".

Request Body Example

body.json

{
  "customer_number": "9876543210",
  "customer_country_code": "+91",
  "customer_name": "Ravi",
  "whatsapp_number": "+91 80000 12345",
  "additional_data": {
    "order_id": "A-1029",
    "plan": "Pro"
  }
}

Notes

status "initiated" (201) means the customer's WhatsApp is ringing — not that they answered. Use the returned id with GET /v1/calls/{id} to read the call once it ends.

status "permission_requested" (202) means nobody is being called yet: the customer was sent your call permission template, and id is null. Call this endpoint again once they accept.

A 409 error carries details.outcome so your code can branch on it: no_permission (request_permission was false), request_limit_reached, or needs_template — plus details.permission when known.

WhatsApp limits permission requests to one per person per day and two per week. Permission granted for a single conversation lapses after 7 days unless the customer made it permanent.

Before calling, the WhatsApp number must be connected, have calling switched on at Meta, and have an assistant — assigned to the number or sent as assistant_id.

All fields are validated up front — a 422 response means nothing happened yet: no message sent, no call placed.

Response Example

response.json

{
  "success": true,
  "data": {
    "id": "665f1a2b3c4d5e6f7a8b9c0d",
    "status": "initiated",
    "customer_number": "9876543210",
    "dialed_number": "919876543210",
    "whatsapp_number": "+91 80000 12345",
    "whatsapp_account_id": "6700a1b2c3d4e5f6a7b8c9d0",
    "provider": "WhatsApp",
    "permission": {
      "status": "granted",
      "expires_at": "2026-09-21T10:00:00.000Z",
      "can_start_call": true,
      "can_request_permission": false
    },
    "additional_data": {
      "order_id": "A-1029",
      "plan": "Pro",
      "name": "Ravi",
      "customerNumber": "9876543210",
      "customerCountryCode": "+91",
      "assignedNumber": "+91 80000 12345"
    }
  }
}

Status Codes

HTTP	Meaning	Description
201	Created	Resource was created.
202	Accepted	Customer has not allowed calls yet — a call permission request was sent instead.
400	Bad request	Malformed input, invalid ObjectId, or no updatable fields.
401	Unauthorized	Missing, invalid, inactive, or origin-restricted API key.
402	Payment required	Insufficient credits, or premium call minutes exhausted.
403	Forbidden	WhatsApp calling is not enabled for this account, or the assistant belongs to another account.
404	Not found	No connected WhatsApp number matches whatsapp_number or whatsapp_account_id.
409	Conflict	The call cannot be placed yet: calling is off at Meta, no assistant, no permission template, the permission request limit is reached, or the customer has not allowed calls and request_permission is false.
415	Unsupported media type	Content-Type header is missing or is not application/json.
422	Validation error	JSON body failed schema or business validation.
429	Rate limited	Per-IP or per-key request budget was exceeded.

Security Model

User-scoped by default

This endpoint only sees resources owned by the user attached to the API key. If another user's id is supplied, the API responds as if the resource does not exist.

curl -X POST "https://api.vomyra.com/v1/whatsapp/calls" \ -H "x-api-key: <api-key>" \ -H "Content-Type: application/json" \ -d '{ "customer_number": "9876543210", "customer_country_code": "+91", "customer_name": "Ravi", "whatsapp_number": "+91 80000 12345", "additional_data": { "order_id": "A-1029", "plan": "Pro" } }'

Initiate WhatsApp Call

Name

Type

Description

customer_numberrequired

string | number

The customer's WhatsApp number. Include the country code, or send a national number with customer_country_code — a number with neither is treated as being in the same country as your WhatsApp number.

customer_namerequired

string

Customer's name — the assistant uses it to address them. 1 to 200 characters.

whatsapp_number

string | number

The connected WhatsApp Business number to call from. Matched on digits, so "+91 80000 12345" and "918000012345" are the same. Provide this or whatsapp_account_id.

whatsapp_account_id

ObjectId

Alternative to whatsapp_number — the id returned by List WhatsApp Numbers.

assistant_id

ObjectId

Assistant that speaks on this call. Defaults to the assistant assigned to the WhatsApp number. Must belong to your account.

customer_country_code

string

Customer's country calling code, digits only with an optional leading + (e.g. "+91"), when customer_number is a national number.

additional_data

object

Arbitrary context passed through to the assistant and stored on the call record (e.g. order_id, plan).

request_permission

boolean

Send the call permission request when the customer has not allowed calls yet. Defaults to true. Set false to get a 409 instead.

template_name

string

Call permission template to send, overriding the one chosen for the number. Must be approved by Meta.

template_language

string

Language code of template_name. Defaults to the number's template language, or "en".

{ "customer_number": "9876543210", "customer_country_code": "+91", "customer_name": "Ravi", "whatsapp_number": "+91 80000 12345", "additional_data": { "order_id": "A-1029", "plan": "Pro" } }

{ "success": true, "data": { "id": "665f1a2b3c4d5e6f7a8b9c0d", "status": "initiated", "customer_number": "9876543210", "dialed_number": "919876543210", "whatsapp_number": "+91 80000 12345", "whatsapp_account_id": "6700a1b2c3d4e5f6a7b8c9d0", "provider": "WhatsApp", "permission": { "status": "granted", "expires_at": "2026-09-21T10:00:00.000Z", "can_start_call": true, "can_request_permission": false }, "additional_data": { "order_id": "A-1029", "plan": "Pro", "name": "Ravi", "customerNumber": "9876543210", "customerCountryCode": "+91", "assignedNumber": "+91 80000 12345" } } }

HTTP

Meaning

Description

201

Created

Resource was created.

202

Accepted

Customer has not allowed calls yet — a call permission request was sent instead.

400

Bad request

Malformed input, invalid ObjectId, or no updatable fields.

401

Unauthorized

Missing, invalid, inactive, or origin-restricted API key.

402

Payment required

Insufficient credits, or premium call minutes exhausted.

403

Forbidden

WhatsApp calling is not enabled for this account, or the assistant belongs to another account.

404

Not found

No connected WhatsApp number matches whatsapp_number or whatsapp_account_id.

409

Conflict

The call cannot be placed yet: calling is off at Meta, no assistant, no permission template, the permission request limit is reached, or the customer has not allowed calls and request_permission is false.

415

Unsupported media type

Content-Type header is missing or is not application/json.

422

Validation error

JSON body failed schema or business validation.

429

Rate limited

Per-IP or per-key request budget was exceeded.