Enviar mensagem - Vistum CRM

curl -X POST https://crm.vistum.com.br/api/v1/conversations/conv_1/messages \
  -H "Authorization: Bearer vg_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Olá! Recebemos seu comprovante, obrigado." }'

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

curl -X POST https://crm.vistum.com.br/api/v1/conversations/conv_1/messages \
  -H "Authorization: Bearer vg_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "document",
    "mediaUrl": "https://cdn.exemplo.com/nota-fiscal.pdf",
    "filename": "nota-fiscal.pdf"
  }'

{ "data": { "id": "msg_10", "status": "sent", "type": "text" } }

POST

api

conversations

{id}

messages

curl -X POST https://crm.vistum.com.br/api/v1/conversations/conv_1/messages \
  -H "Authorization: Bearer vg_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Olá! Recebemos seu comprovante, obrigado." }'

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

curl -X POST https://crm.vistum.com.br/api/v1/conversations/conv_1/messages \
  -H "Authorization: Bearer vg_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "document",
    "mediaUrl": "https://cdn.exemplo.com/nota-fiscal.pdf",
    "filename": "nota-fiscal.pdf"
  }'

{ "data": { "id": "msg_10", "status": "sent", "type": "text" } }

Autenticação

string

required

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

Envia uma mensagem por uma conversa que já existe, reusando a mesma infra do chat humano: mesma checagem de janela de 24h, mesma cota diária de mensagens do plano e mesmo tratamento de erro do provedor. Rate limit: perfil de envio (teto absoluto 15 mensagens/min por chave, fail-closed).

Para iniciar uma conversa com um número novo (sem conversa prévia), use POST /api/v1/messages, que cria o contato e a conversa automaticamente.

O corpo é discriminado pelo campo type. Quando type é omitido, a mensagem é tratada como texto (retrocompatível com clientes que enviam apenas { "text": "..." }).

`type`	Envia	Janela de 24h (API Oficial)
`text` (padrão)	Texto livre	Exige janela aberta
`image` / `video` / `audio` / `document`	Mídia por URL pública	Exige janela aberta
`template`	Template Meta aprovado	Funciona fora da janela (reengajamento)

Na API Oficial (Cloud), fora da janela de 24h só é possível enviar template aprovado. Texto/mídia fora da janela retornam 422 WINDOW_CLOSED. Cada envio consome a cota diária de mensagens do plano.

Body

string

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

string

Obrigatório quando type é text. Texto da mensagem (1 a 4096 caracteres).

string

Obrigatório para mídia. URL https pública de onde a Meta/Evolution baixa o arquivo (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 WABA.

string

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

string[]

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

Limites de mídia (Meta)

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

curl -X POST https://crm.vistum.com.br/api/v1/conversations/conv_1/messages \
  -H "Authorization: Bearer vg_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Olá! Recebemos seu comprovante, obrigado." }'

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

curl -X POST https://crm.vistum.com.br/api/v1/conversations/conv_1/messages \
  -H "Authorization: Bearer vg_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "document",
    "mediaUrl": "https://cdn.exemplo.com/nota-fiscal.pdf",
    "filename": "nota-fiscal.pdf"
  }'

{ "data": { "id": "msg_10", "status": "sent", "type": "text" } }

Erros de envio

HTTP	`code`	Causa
`400`	`BAD_REQUEST`	ID da conversa ausente ou JSON inválido.
`400`	`VALIDATION`	O corpo não corresponde a `text`/mídia/`template`.
`404`	`NOT_FOUND`	Conversa inexistente ou de outro workspace.
`409`	`INSTANCE_ARCHIVED`	A conexão foi arquivada.
`422`	`CHANNEL_UNSUPPORTED`	O envio pela API só é suportado no WhatsApp.
`422`	`INSTANCE_NOT_READY`	Conexão da API Oficial sem credenciais configuradas.
`422`	`WINDOW_CLOSED`	Janela de 24h fechada (Cloud) — só template aprovado seria aceito.
`422`	`INSTANCE_DISCONNECTED`	WhatsApp desconectado (Evolution).
`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`	`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 inválido ou sem WhatsApp.
`429`	`MESSAGE_LIMIT_REACHED`	Cota diária de mensagens do plano atingida.
`402`	`SUBSCRIPTION_INACTIVE`	Assinatura inativa.
`502`	`SEND_FAILED`	Falha do provedor no envio.

​Autenticação

​Body

​Limites de mídia (Meta)

​Erros de envio

Autenticação

Body

Limites de mídia (Meta)

Erros de envio