Iniciar Chamada

POST /v1/calls Cria e enfileira uma chamada de saída no WhatsApp a partir de uma instância. Suporta quatro tipos de chamada: FIXED_TTS, FIXED_AUDIO, DYNAMIC_STREAM e DYNAMIC_AGENT. Se a instância já possuir uma chamada ativa (QUEUED, RINGING ou IN_PROGRESS), a chamada existente é retornada (200) em vez de criar uma duplicata.

Requisição

Cabeçalhos

Cabeçalho	Valor
`Authorization`	`Bearer <token>`
`Content-Type`	`application/json`

Corpo

Campo	Tipo	Obrigatório	Descrição
`instanceId`	`string`	Sim	A instância a partir da qual a chamada será realizada
`type`	`string`	Sim	Tipo de chamada: `FIXED_TTS`, `FIXED_AUDIO`, `DYNAMIC_STREAM` ou `DYNAMIC_AGENT`
`target.phoneNumber`	`string`	Sim	Número de destino no formato E.164 (ex.: `+14155550123`)
`tts.text`	`string`	Apenas FIXED_TTS	A mensagem a ser falada
`tts.voiceId`	`string`	Apenas FIXED_TTS	Identificador da voz (ex.: `pt-BR-001`)
`audio.audioBase64`	`string`	Apenas FIXED_AUDIO	Arquivo de áudio codificado em Base64
`agent.instructions`	`string[]`	Apenas DYNAMIC_AGENT	Instruções em linguagem natural para o agente de IA

Exemplos

FIXED_TTS
FIXED_AUDIO
DYNAMIC_STREAM
DYNAMIC_AGENT

{
  "instanceId": "inst_abc123",
  "type": "FIXED_TTS",
  "target": { "phoneNumber": "+14155550123" },
  "tts": {
    "text": "Olá, esta é uma ligação da ACME Corp.",
    "voiceId": "pt-BR-001"
  }
}

{
  "instanceId": "inst_abc123",
  "type": "FIXED_AUDIO",
  "target": { "phoneNumber": "+14155550123" },
  "audio": {
    "audioBase64": "SUQzBAAAAAAA..."
  }
}

{
  "instanceId": "inst_abc123",
  "type": "DYNAMIC_STREAM",
  "target": { "phoneNumber": "+14155550123" }
}

{
  "instanceId": "inst_abc123",
  "type": "DYNAMIC_AGENT",
  "target": { "phoneNumber": "+14155550123" },
  "agent": {
    "instructions": [
      "Cumprimente a pessoa educadamente",
      "Pergunte se ela tem interesse em uma demonstração",
      "Se sim, agende um follow-up"
    ]
  }
}

Resposta

`201` — Chamada criada

Campo	Tipo	Descrição
`id`	`string`	ID único da chamada (prefixo `call_`)
`instance_id`	`string`	Instância que realizou a chamada
`type`	`string`	Tipo de chamada
`status`	`string`	Sempre `QUEUED` na criação
`target_phone`	`string`	Número de destino
`created_at`	`string`	Timestamp ISO 8601

{
  "id": "call_xyz789",
  "instance_id": "inst_abc123",
  "type": "FIXED_TTS",
  "status": "QUEUED",
  "target_phone": "+14155550123",
  "created_at": "2026-03-01T10:01:00Z"
}

`200` — Chamada ativa existente retornada

Quando a instância já possui uma chamada ativa, o objeto da chamada existente é retornado com status 200.

Erros

Código	Descrição
`400`	`instanceId`, `type` ou `target.phoneNumber` está ausente; valor de `type` inválido
`401`	Token ausente ou inválido
`403`	Token demo utilizado com instância incorreta
`404`	Instância não encontrada ou não pertence ao usuário

Exemplo

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": "Olá, esta é uma ligação da ACME Corp.",
      "voiceId": "pt-BR-001"
    }
  }'

​Requisição

​Cabeçalhos

​Corpo

​Exemplos

​Resposta

​201 — Chamada criada

​200 — Chamada ativa existente retornada

​Erros

​Exemplo