Enviar mensagem para um número novo

Autenticação

string

required

Bearer vg_live_<sua_chave> — API Key com escopo conversations:send (escopo dedicado, sem herança de conversations:read).

Diferente de POST /conversations/{id}/messages — que exige uma conversa já existente — este endpoint recebe apenas o phone: ele faz find-or-create do contato e da conversa e então envia, reusando a mesma infraestrutura do chat humano (janela de 24h, cota diária de mensagens do plano, primitivos do provedor e mapeamento de erro da Meta). POST /api/v1/messages · Escopo conversations:send · Rate limit: perfil de envio a frio (send-cold)

Este é o recurso mais sensível da API — envio para números novos (cold outreach). Ele tem limites mais apertados que o envio em conversa existente: 10 req/min por IP e teto absoluto de 5 mensagens/min por chave (fail-closed), além de um cap diário de números novos por workspace. Cada envio consome a cota diária de mensagens do plano.

Como escolher o `type`

O corpo é discriminado pelo campo type. Quando type é omitido, assume-se text.

`type`	Envia	Campos
`text` (padrão)	Texto livre	`text`
`image` / `video` / `audio` / `document`	Mídia por URL pública	`mediaUrl`, `caption?`, `filename?`
`template`	Template Meta aprovado	`templateName`, `language`, `variables?`

Regra da Meta para número novo (API Oficial / Cloud): um número sem conversa prévia está fora da janela de 24h. A Meta só aceita template aprovado nesse caso. Enviar text ou mídia para um número novo em uma conexão Cloud retorna 422 WINDOW_CLOSED.

Conexão Evolution (não oficial): o envio de texto livre para número novo funciona, mas fazer cold outreach por uma conexão Evolution tem risco real de banimento do número pelo WhatsApp. Para prospecção em escala, use a API Oficial com template aprovado.

Formato do telefone

O campo phone exige o número internacional brasileiro completo: 55 + DDD (2 dígitos) + número. O formato é flexível — +, espaços, parênteses e traços são ignorados —, mas o 55 e o DDD são obrigatórios.

5511987654321      ✅ celular com o 9º dígito
+55 (11) 98765-4321 ✅ mesmo número, formatado
551187654321       ✅ celular na forma canônica da Meta (sem o 9)
551133334444       ✅ telefone fixo
11987654321        ❌ sem o 55 → 400 INVALID_PHONE
987654321          ❌ sem DDD → 400 INVALID_PHONE

9º dígito: as duas formas do mesmo celular — com o 9 (5511987654321) e sem o 9 (551187654321) — resolvem no mesmo contato e na mesma conversa. Você não precisa saber qual forma a Meta usa: o CRM canonicaliza no matching (igual ao webhook de entrada) e, no envio Cloud, ainda reconcilia com o wa_id autoritativo devolvido pela Meta, para que a resposta do lead caia sempre na mesma conversa. Números ambíguos (sem 55/DDD) são rejeitados com 400 INVALID_PHONE — o CRM não adivinha país nem DDD, para não criar contato duplicado.

Body

string

required

Telefone do destinatário no formato 55 + DDD + número (ex.: 5511987654321). Máx. 32 caracteres.

string

Conexão (instância WhatsApp) usada para enviar. Opcional quando o workspace tem uma única conexão. Obrigatório quando há mais de uma (senão retorna 422 INSTANCE_REQUIRED). Obtenha os IDs em GET /instances.

string

text (padrão), image, video, audio, document ou template.

string

Obrigatório quando type é text. Conteúdo da mensagem, 1 a 4096 caracteres.

string

Obrigatório para mídia (image/video/audio/document). URL https pública de onde a Meta/Evolution baixa o arquivo (passa por checagem anti-SSRF). Máx. 2048 caracteres.

string

Legenda opcional da mídia (máx. 1024 caracteres).

string

Nome do arquivo exibido, útil para document (máx. 255 caracteres).

string

Obrigatório para template. Nome exato do template aprovado na sua WABA.

string

Obrigatório para template. Código de idioma do template (ex.: pt_BR). 2 a 15 caracteres.

string[]

Valores posicionais das variáveis do corpo do template, na ordem — a 1ª entrada preenche {{1}}, a 2ª {{2}}, e assim por diante. Máx. 20 valores, cada um até 1024 caracteres. A contagem precisa bater com o template aprovado (senão 422 TEMPLATE_INVALID).

Limites de mídia (Meta)

Tipo	Limite
`image`	5 MB
`video`	16 MB
`audio`	16 MB
`document`	100 MB

Mídia acima do limite retorna 422 MEDIA_TOO_LARGE.

Idempotência

Envie o header opcional Idempotency-Key (qualquer string única sua, ex.: um UUID) para evitar envio duplicado em retries. A chave é reservada atomicamente antes do envio: dois POSTs concorrentes com a mesma chave nunca enviam duas vezes — o segundo recebe 409 IN_PROGRESS (ainda em andamento) ou a resposta memoizada (200, mesmo corpo) por 10 minutos. Uma falha de envio libera a reserva para permitir novo retry com a mesma chave.

Idempotency-Key: 6f9619ff-8b86-d011-b42d-00cf4fc964ff

Exemplos

curl -X POST https://crm.vistum.com.br/api/v1/messages \
  -H "Authorization: Bearer vg_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f9619ff-8b86-d011-b42d-00cf4fc964ff" \
  -d '{
    "phone": "5511987654321",
    "text": "Olá! Aqui é da Loja X, tudo bem?",
    "instanceId": "inst_a1"
  }'

curl -X POST https://crm.vistum.com.br/api/v1/messages \
  -H "Authorization: Bearer vg_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511987654321",
    "type": "template",
    "templateName": "boas_vindas",
    "language": "pt_BR",
    "variables": ["João", "10%"],
    "instanceId": "inst_a1"
  }'

curl -X POST https://crm.vistum.com.br/api/v1/messages \
  -H "Authorization: Bearer vg_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511987654321",
    "type": "image",
    "mediaUrl": "https://cdn.exemplo.com/promo.jpg",
    "caption": "Nossa promoção da semana",
    "instanceId": "inst_a1"
  }'

{
  "data": {
    "id": "msg_10",
    "status": "sent",
    "type": "text",
    "conversationId": "conv_7",
    "contactId": "contact_3",
    "created": { "contact": true, "conversation": true }
  }
}

Resposta 201

string

ID interno da mensagem criada no CRM.

string

Sempre sent quando a resposta é 201.

string

text, image, video, audio, document ou template.

string

Conversa (nova ou existente) onde a mensagem foi registrada.

string

Contato (novo ou existente) resolvido pelo telefone.

object

{ "contact": boolean, "conversation": boolean } — indica se o contato e/ou a conversa foram criados por esta requisição (false = já existiam).

Se o envio falhar depois de criar contato/conversa (ex.: WINDOW_CLOSED, TEMPLATE_INVALID, Evolution desconectada), o CRM faz rollback: remove o contato/conversa recém-criados e devolve a cota e o slot diário — nada de contato fantasma nem cota queimada por uma tentativa que não entregou.

Fluxo recomendado

Descubra o instanceId com GET /api/v1/instances (necessário se o workspace tiver mais de uma conexão; escolha uma connected).
Envie com POST /api/v1/messages, usando Idempotency-Key para tornar o retry seguro.
Para número novo em conexão Cloud, use sempre type: "template" — texto/mídia caem em 422 WINDOW_CLOSED.

Erros

Autenticação e limites

HTTP	`code`	Causa
`401`	`UNAUTHORIZED`	API Key ausente ou inválida.
`401`	`KEY_EXPIRED`	A chave expirou.
`403`	`FORBIDDEN_SCOPE`	A chave não tem o escopo `conversations:send`.
`402`	`API_ACCESS_REQUIRED`	O plano do workspace não inclui acesso à API.
`402`	`SUBSCRIPTION_INACTIVE`	Assinatura cancelada/suspensa/vencida.
`429`	`RATE_LIMIT_IP`	Mais de 10 req/min a partir do mesmo IP.
`429`	`RATE_LIMIT_KEY`	Teto de 5 mensagens/min por chave atingido.

Corpo e roteamento

HTTP	`code`	Causa
`400`	`BAD_REQUEST`	JSON inválido no corpo.
`400`	`VALIDATION`	O corpo não corresponde a nenhum formato (`text`/mídia/`template`).
`400`	`INVALID_PHONE`	`phone` sem `55` + DDD, ou número ambíguo.
`409`	`IN_PROGRESS`	Já existe uma requisição em andamento com o mesmo `Idempotency-Key`.
`422`	`INSTANCE_REQUIRED`	Há mais de uma conexão — informe `instanceId`.
`422`	`NO_INSTANCE`	O workspace não tem nenhuma conexão WhatsApp.
`404`	`INSTANCE_NOT_FOUND`	O `instanceId` informado não existe neste workspace.
`403`	`OPTED_OUT`	O contato solicitou opt-out de marketing.
`429`	`COLD_LIMIT_REACHED`	Cap diário de números novos do workspace atingido.
`402`	`CONTACT_LIMIT_REACHED`	Limite de contatos do plano atingido.

Envio

HTTP	`code`	Causa
`422`	`WINDOW_CLOSED`	Número novo em conexão Cloud fora da janela de 24h — use um template aprovado.
`422`	`TEMPLATE_REQUIRES_OFFICIAL`	`template` só é enviável por uma conexão da API Oficial.
`422`	`TEMPLATE_INVALID`	Template inexistente, não aprovado, ou nº de variáveis não bate.
`422`	`INSTANCE_DISCONNECTED`	Conexão Evolution desconectada.
`422`	`INSTANCE_NOT_READY`	Conexão da API Oficial sem credenciais configuradas.
`409`	`INSTANCE_ARCHIVED`	A conexão foi arquivada.
`422`	`CHANNEL_UNSUPPORTED`	O envio pela API só é suportado no WhatsApp.
`422`	`MEDIA_URL_INVALID`	`mediaUrl` inválida, não-https ou insegura (anti-SSRF).
`422`	`MEDIA_TOO_LARGE`	Mídia acima do limite da Meta.
`422`	`NUMBER_INVALID`	Número sem WhatsApp.
`429`	`MESSAGE_LIMIT_REACHED`	Cota diária de mensagens do plano atingida.
`502`	`SEND_FAILED`	Falha do provedor ao enviar.

​Autenticação

​Como escolher o type

​Formato do telefone

​Body

​Limites de mídia (Meta)

​Idempotência

​Exemplos

​Resposta 201

​Fluxo recomendado

​Erros

​Autenticação e limites

​Corpo e roteamento

​Envio

Autenticação

Como escolher o `type`

Formato do telefone

Body

Limites de mídia (Meta)

Idempotência

Exemplos

Resposta 201

Fluxo recomendado

Erros

Autenticação e limites

Corpo e roteamento

Envio