Place a WhatsApp call

Place an outbound WhatsApp voice call after the customer has granted permission

Updated 15 Aug 2026

On this page

Queues an outbound WhatsApp voice call. Your sender's assistant joins the call when the customer answers.

The customer must have granted call permission and that consent must still be valid. This endpoint will not call a number that never allowed calling.

Rate-limited to 5 requests per minute, 15 per hour, and 30 per day per user. Also limited to 3 attempts per contact every 5 minutes and 5 WhatsApp calls in progress on the same sender.

Request Body

sender_idintegerrequired

WhatsApp sender ID with calling enabled

recipient_phonestringrequired

Customer phone number in E.164 format

variablesobject

Optional variables passed to the assistant (max 20 keys, string values up to 500 characters). Use the same names you configured on the assistant.

Response Fields

successboolean

The call was queued

statusstring

Always queued on success. The call is placed asynchronously.

sender_idinteger

Sender used for the call

customer_phonestring

Normalized E.164 phone number

Error codes

HTTP	`error_code`	Meaning
402	`INSUFFICIENT_BALANCE`	Account balance is too low
403	`ASSISTANT_BLOCKED`	Assistant is unavailable for compliance review
404	`SENDER_NOT_FOUND`	Sender missing or not yours
422	`INVALID_PHONE`	Phone is not valid E.164
422	`VOICE_DISABLED`	Calling is not enabled
422	`NO_PERMISSION`	Customer has not granted (or consent expired)
422	`NO_ASSISTANT`	Sender has no assistant
422	`SENDER_OFFLINE`	Sender is not online
422	`REGION_NOT_SUPPORTED`	WhatsApp does not allow business-initiated calls from this sender's country
422	`FEATURE_DISABLED`	Calling is not available on this workspace
429	`CONCURRENT_LIMIT`	Too many WhatsApp calls already ringing on this sender
429	`CONTACT_RATE_LIMIT`	Too many attempts to this contact in the last 5 minutes

curl -X POST "https://app.voxlink.ai/api/user/whatsapp/voice/call" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": 12,
    "recipient_phone": "+40711222333",
    "variables": {
      "customer_name": "Ana Pop"
    }
  }'

const response = await fetch(
  'https://app.voxlink.ai/api/user/whatsapp/voice/call',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      sender_id: 12,
      recipient_phone: '+40711222333',
      variables: { customer_name: 'Ana Pop' },
    }),
  }
);

console.log(await response.json());

import requests

response = requests.post(
    'https://app.voxlink.ai/api/user/whatsapp/voice/call',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'sender_id': 12,
        'recipient_phone': '+40711222333',
        'variables': {'customer_name': 'Ana Pop'},
    },
)

print(response.json())

{
  "success": true,
  "status": "queued",
  "sender_id": 12,
  "customer_phone": "+40711222333"
}

{
  "success": false,
  "error": "This contact has not granted permission to receive WhatsApp calls. Send a call permission request first.",
  "error_code": "NO_PERMISSION"
}

After you queue the call

A call_started event is sent to the WhatsApp voice webhook when the call is placed
When the call finishes, the assistant's post-call webhook fires as usual (transcript, duration, extracted variables)
The response does not include provider call IDs

Read WhatsApp Calling before you automate this. Cold-calling new numbers is not possible.

Related guides

API Reference

Introduction

Welcome to the VoxLink API

Read guide →

API Reference

Authentication

Learn how to authenticate your API requests

Read guide →

API Reference

Get current user

Get the authenticated user's profile information

Read guide →

API Reference

List assistants

List all assistants for the authenticated user with pagination

Read guide →