Skip to main content
POST
Criar nova campanha (voz ou WhatsApp)

Canais

O campo channel decide o tipo de campanha. Ele é opcional e vale voice quando você não envia. Os campos comuns aos dois canais são name, project_id, scheduled_at e recipients.
No canal voice, scheduled_at precisa ser no futuro. No canal whatsapp, uma data no passado é aceita e dispara no próximo ciclo do worker — é assim que você agenda um “enviar agora”.

Campanha de WhatsApp

Variáveis do template

O corpo do template usa marcadores numerados: Oi {{1}}, seu horário é {{2}}. Cada destinatário preenche esses marcadores pelo dynamic_variables, com chaves numéricas em texto:
A chave "n" preenche o {{n}} do corpo. O que vale é a posição, não o nome: chaves como leadName só são aceitas no canal voice.
A quantidade de variáveis de cada destinatário tem que bater com o número de {{n}} do corpo. Faltando ou sobrando, a campanha inteira é recusada com 422 antes de qualquer disparo — nenhuma mensagem é enviada. Confira o corpo do template no painel, em Templates.

Antes de criar

Cada número de WhatsApp tem um limite de conversas que pode iniciar em 24h, definido pela Meta. Uma lista maior que o disponível é recusada com 422. Consulte as conversas disponíveis antes de montar a lista.

Exemplos

Campanhas de WhatsApp respondem com agent, phone_number e config nulos: elas não têm agente de voz, número de origem próprio nem parâmetros de discagem.

Erros

422 — variáveis que não batem com o corpo

A validação roda sobre a lista inteira e para no primeiro destinatário irregular. A mensagem diz quantas variáveis o corpo exige e qual número está errado:

422 — quota de conversas excedida

O 502 na criação não garante que a campanha deixou de ser criada. A criação é gravada do outro lado em transação própria e pode ter sido concluída depois de estourar o tempo de resposta desta chamada.Antes de repetir a requisição, liste suas campanhas e procure pelo name que você enviou. Repetir às cegas cria uma segunda campanha, e a lista inteira recebe o template duas vezes, consumindo quota da Meta em dobro. Não há como desfazer um disparo já entregue.

Authorizations

Authorization
string
header
required

API Key da organização (Authorization: Bearer ik_live_xxx)

Body

application/json
name
string
required
Minimum string length: 1
Example:

"Campanha Março 2026"

project_id
string
required

Project ID (copy from Panel → project header)

Example:

"b9c80a57-fad2-41a0-a304-727337ad1b1f"

scheduled_at
string
required

ISO 8601 datetime with timezone (e.g. 2026-03-24T14:00:00Z)

Example:

"2026-03-25T14:00:00Z"

recipients
object[]
required

List of recipients (max 10,000)

Required array length: 1 - 10000 elements
channel
enum<string>
default:voice

Campaign channel: voice (outbound calls, default) or whatsapp (approved template broadcast)

Available options:
voice,
whatsapp
Example:

"voice"

agent_id
string

Agent ID (copy from Panel → agent card). Required for voice campaigns

Example:

"7e09d093-904a-48de-ac49-b0445906c38e"

phone_number_id
string

Phone number ID assigned to the agent. Required for voice campaigns

Example:

"d1082e49-1b2c-4337-81e2-8eb74810351d"

template_name
string

Approved WhatsApp template name. Required for whatsapp campaigns

Example:

"boas_vindas_pt_br"

meta_phone_external_id
string

Meta phone number ID used as sender. Optional when the organization has a single WhatsApp number

Example:

"109876543210987"

config
object

Response

Campanha criada

id
string
required
name
string
required
status
string
required
channel
string
required
template_name
string | null
required
scheduled_at
string
required
agent
object | null
required
phone_number
object | null
required
total_recipients
number
required
created_at
string
required
config
any