Enviar mensagem

Endpoint

POST /v1/messages/send

Também disponível como POST /v1/conversations/send (alias). Escopo necessário: write:messages

Canais suportados

Canal	Requisito no contato
`whatsapp`	Telefone válido, preferencialmente no formato internacional com DDI, como `+5511999999999`
`messenger`	`messenger_psid` preenchido

O canal Instagram não está disponível na API pública neste momento.

Você não precisa conhecer nem informar JID ou outro identificador interno do WhatsApp. A SocialSell resolve o destinatário a partir do telefone e também autorrepara contatos antigos no primeiro envio.

Rate limits por canal

Independentes do plano e cumulativos com o limite por minuto da chave:

Canal	Limite	Código do erro
WhatsApp	30 mensagens/min por número	`WHATSAPP_INSTANCE_RATE_LIMIT`
Messenger	30 mensagens/min por página	`MESSENGER_PAGE_RATE_LIMIT`

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`contact_id`	string	Sim	ID do contato destinatário
`channel`	string	Sim	`whatsapp` ou `messenger`
`type`	string	Não	`text` (padrão), `image`, `video`, `audio`, `document`
`content`	string	Condicional	Texto da mensagem. Obrigatório quando `type=text`, exceto em envio de modelo (`template_name`)
`media_url`	string	Condicional	URL pública da mídia. Obrigatório para tipos não-texto
`whatsapp_instance_id`	string	Não	ID da instância WhatsApp. Se omitido, usa a instância conectada disponível
`messenger_page_id`	string	Não	ID local da conexão Messenger. Se omitido, o contato precisa ter vínculo único comprovado; ambiguidade retorna `409 CONNECTION_REQUIRED`
`template_name`	string	Não	Nome do modelo aprovado. Só funciona em número do WhatsApp Oficial
`template_language`	string	Não	Idioma do modelo. Padrão: `pt_BR`. Precisa bater exatamente com o modelo aprovado
`template_components`	array	Não	Componentes e variáveis do modelo, no formato da Meta

Comportamento de conversa

Se não existir conversa entre o contato e aquele número ou página, uma é criada automaticamente. A resposta sempre traz o conversation_id.

Escolha do número

`whatsapp_instance_id`	O que acontece
Informado	Usa exatamente esse número — sem verificar se está conectado
Omitido	Escolhe automaticamente um número com status `connected`

Informar um número desconectado não devolve NO_WHATSAPP_INSTANCE: a requisição segue e falha mais adiante. Omitir o campo é mais seguro quando você não precisa de um número específico.

Idempotência

Esta rota aceita Idempotency-Key — repetir depois de um timeout não envia a mensagem duas vezes. Ver Idempotência.

Exemplos

Texto via WhatsApp

curl -X POST https://api.socialsell.ai/v1/messages/send \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "664f1a2b3c4d5e6f78901234",
    "channel": "whatsapp",
    "type": "text",
    "content": "Olá! Sua proposta foi aprovada. Podemos agendar uma reunião?"
  }'

Imagem via WhatsApp

curl -X POST https://api.socialsell.ai/v1/messages/send \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "664f1a2b3c4d5e6f78901234",
    "channel": "whatsapp",
    "type": "image",
    "media_url": "https://meusistema.com/proposta.jpg",
    "content": "Segue a proposta em anexo!"
  }'

Modelo do WhatsApp Oficial

Com template_name informado, content, type e media_url não são usados — o texto vem do modelo aprovado.

Modelo só existe no WhatsApp Oficial. Em um número por QR Code a API devolve 422 TEMPLATE_REQUIRES_OFFICIAL_NUMBER. Confirme o canal do número antes: o campo channel (official | qrcode) aparece em whatsapp_instances de um disparo.

O modelo precisa estar aprovado (APPROVED), pertencer àquele número e bater com o template_language informado. Caso contrário: 422 TEMPLATE_NOT_FOUND.

curl -X POST https://api.socialsell.ai/v1/messages/send \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "664f1a2b3c4d5e6f78901234",
    "channel": "whatsapp",
    "template_name": "boas_vindas",
    "template_language": "pt_BR",
    "template_components": [
      {
        "type": "body",
        "parameters": [
          {"type": "text", "text": "João Silva"}
        ]
      }
    ]
  }'

Texto via Messenger

curl -X POST https://api.socialsell.ai/v1/messages/send \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "664f1a2b3c4d5e6f78901234",
    "channel": "messenger",
	"messenger_page_id": "665f1a2b3c4d5e6f78901234",
    "type": "text",
    "content": "Olá! Vi seu interesse no nosso produto. Posso ajudar?"
  }'

O ID explícito deve ser da mesma organização e corresponder à identidade Messenger do contato. O servidor nunca escolhe “a primeira página” quando o vínculo não é único.

Respostas

Retorna HTTP 201. O corpo tem duas formas, conforme o caminho de envio.

Texto e mídia

{
  "data": {
    "id": "664d100d2ac9437188591880",
    "conversation_id": "664632f1260b42723a5ed4ed",
    "content": "Olá! Sua proposta foi aprovada.",
    "type": "text",
    "sender": "agent",
    "status": "sent",
    "sent_at": "2026-06-10T16:00:00.000Z"
  },
  "meta": { "request_id": "req_a1b2c3d4e5f6a7b8" }
}

Modelo do WhatsApp Oficial

{
  "data": {
    "id": "664d100d2ac9437188591880",
    "conversation_id": "664632f1260b42723a5ed4ed",
    "content": "Olá, Maria! Seu pedido 4821 foi confirmado.",
    "type": "template",
    "sender": "agent",
    "status": "sent",
    "sent_at": "2026-06-10T16:00:00.000Z",
    "external_id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjhGN0..."
  },
  "meta": { "request_id": "req_a1b2c3d4e5f6a7b8" }
}

external_id só existe na resposta de modelo. Nos envios de texto e mídia o campo não vem — ele é gravado na mensagem, mas não devolvido. Se a sua integração concilia pelo identificador da Meta, leia depois em GET /v1/conversations/:id/messages.

No envio de modelo, type vem como template — valor fora da lista de type da requisição — e content traz o corpo do modelo com os parâmetros de template_components aplicados — o texto que o contato recebeu. Só um modelo sem texto no corpo devolve o rótulo [Modelo: nome].

Erros

Código	Status	Descrição
`MISSING_REQUIRED_FIELD`	`400`	`contact_id` ausente
`INVALID_CHANNEL`	`400`	Canal inválido
`CHANNEL_NOT_SUPPORTED`	`400`	Instagram ainda não suportado
`MISSING_CONTENT`	`400`	`content` ausente para mensagem de texto
`MISSING_MEDIA_URL`	`400`	`media_url` ausente para mensagens de mídia
`CONTACT_NOT_FOUND`	`404`	Contato não encontrado
`NO_WHATSAPP_JID`	`422`	Código legado devolvido quando o contato não possui telefone utilizável. A mensagem orienta cadastrar um telefone válido com DDI e o corpo traz `reason: "WHATSAPP_PHONE_REQUIRED"`
`NO_WHATSAPP_INSTANCE`	`422`	Sem instância WhatsApp conectada
`NO_MESSENGER_PSID`	`422`	Contato sem PSID Messenger
`NO_MESSENGER_PAGE`	`422`	Sem página Messenger conectada
`TEMPLATE_REQUIRES_OFFICIAL_NUMBER`	`422`	`template_name` informado, mas o número é por QR Code. Modelo só existe no WhatsApp Oficial
`TEMPLATE_NOT_FOUND`	`422`	Nenhum modelo aprovado com esse nome e idioma neste número
`TEMPLATE_PARAMETERS_MISSING`	`422`	O texto do modelo tem variáveis sem valor em `template_components`. `missing` lista quais (`["1", "2"]`). Nada é enviado nem gravado na conversa
`TEMPLATE_SEND_ERROR`	`422`	A Meta recusou o envio do modelo. A mensagem traz o motivo
`TEMPLATE_NOT_CONFIRMED`	`502`	O WhatsApp Oficial não confirmou o envio. A mensagem fica como `failed`
`MESSENGER_SEND_ERROR`	`500`	Erro devolvido pela API do Messenger
`WHATSAPP_INSTANCE_RATE_LIMIT`	`429`	30 msg/min por número atingido
`MESSENGER_PAGE_RATE_LIMIT`	`429`	30 msg/min por página atingido

Contatos

Empresas

Negócios

Funis de venda

Conversas

Mensagens

Tarefas

Campos personalizados

Agentes de IA

Disparos

Créditos de mensagem

Lookup

Endpoint

Canais suportados

Rate limits por canal

Corpo da requisição

Comportamento de conversa

Escolha do número

Idempotência

Exemplos

Texto via WhatsApp

Imagem via WhatsApp

Modelo do WhatsApp Oficial

Texto via Messenger

Respostas

Texto e mídia

Modelo do WhatsApp Oficial

Erros

​Endpoint

​Canais suportados

​Rate limits por canal

​Corpo da requisição

​Comportamento de conversa

​Escolha do número

​Idempotência

​Exemplos

​Texto via WhatsApp

​Imagem via WhatsApp

​Modelo do WhatsApp Oficial

​Texto via Messenger

​Respostas

​Texto e mídia

​Modelo do WhatsApp Oficial

​Erros

Endpoint

Canais suportados

Rate limits por canal

Corpo da requisição

Comportamento de conversa

Escolha do número

Idempotência

Exemplos

Texto via WhatsApp

Imagem via WhatsApp

Modelo do WhatsApp Oficial

Texto via Messenger

Respostas

Texto e mídia

Modelo do WhatsApp Oficial

Erros