Skip to main content
POST /v1/calls Creates and queues an outbound WhatsApp call from an instance. Supports four call types: FIXED_TTS, FIXED_AUDIO, DYNAMIC_STREAM, and DYNAMIC_AGENT. If the instance already has an active call (QUEUED, RINGING, or IN_PROGRESS), the existing call is returned (200) instead of creating a duplicate.

​
Request

​
Headers

HeaderValue
AuthorizationBearer <token>
Content-Typeapplication/json

​
Body

FieldTypeRequiredDescription
instanceIdstringYesThe instance to place the call from
typestringYesCall type: FIXED_TTS, FIXED_AUDIO, DYNAMIC_STREAM, or DYNAMIC_AGENT
target.phoneNumberstringYesDestination phone number in E.164 format (e.g., +14155550123)
tts.textstringFIXED_TTS onlyThe message to speak
tts.voiceIdstringFIXED_TTS onlyVoice identifier (e.g., en-US-001)
audio.audioBase64stringFIXED_AUDIO onlyBase64-encoded audio file
agent.instructionsstring[]DYNAMIC_AGENT onlyNatural-language instructions for the AI agent

​
Examples

{
  "instanceId": "inst_abc123",
  "type": "FIXED_TTS",
  "target": { "phoneNumber": "+14155550123" },
  "tts": {
    "text": "Hello, this is a call from ACME Corp.",
    "voiceId": "en-US-001"
  }
}

​
Response

​
201 — Call created

FieldTypeDescription
idstringUnique call ID (call_ prefix)
instance_idstringInstance that placed the call
typestringCall type
statusstringAlways QUEUED on creation
target_phonestringDestination phone number
created_atstringISO 8601 timestamp
{
  "id": "call_xyz789",
  "instance_id": "inst_abc123",
  "type": "FIXED_TTS",
  "status": "QUEUED",
  "target_phone": "+14155550123",
  "created_at": "2026-03-01T10:01:00Z"
}

​
200 — Existing active call returned

When the instance already has an active call, the existing call object is returned with status 200.

​
Errors

CodeDescription
400instanceId, type, or target.phoneNumber is missing; invalid type value
401Missing or invalid token
403Demo token used with wrong instance
404Instance not found or does not belong to the user

​
Example

curl -X POST https://cawme.com/api/v1/calls \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "inst_abc123",
    "type": "FIXED_TTS",
    "target": { "phoneNumber": "+14155550123" },
    "tts": {
      "text": "Hello, this is a call from ACME Corp.",
      "voiceId": "en-US-001"
    }
  }'