Enviar Mensagem

Endpoints para envio de mensagens do WhatsApp com diferentes tipos de conteúdo.

Campos Opcionais Comuns

Todos os endpoints de envio de mensagem suportam os seguintes campos opcionais:

• delay (integer): Atraso em milissegundos antes do envio

  • Durante o atraso aparecerá "Digitando..." ou "Gravando áudio..." dependendo do tipo
  • Exemplo: 5000 (5 segundos)

• readchat (boolean): Marcar chat como lido após envio

  • Remove o contador de mensagens não lidas do chat
  • Exemplo: true

• readmessages (boolean): Marcar últimas mensagens recebidas como lidas

  • Marca as últimas 10 mensagens recebidas (não enviadas por você) como lidas
  • Útil para confirmar leitura de mensagens pendentes antes de responder
  • Diferente do readchat que apenas remove contador de não lidas
  • Exemplo: true

• replyid (string): ID da mensagem para responder

  • Cria uma resposta vinculada à mensagem original
  • Suporte varia por tipo de mensagem

• viewOnce (boolean): Recomendado quando quiser mídia de visualização única

  • Use em /send/media com type compatível (image, video, videoplay, ptv, audio, myaudio, ptt)
  • Nos demais endpoints de envio, o campo é aceito, mas é ignorado silenciosamente
  • Exemplo: "3A12345678901234567890123456789012"

• mentions (string): Números para mencionar (apenas para envio em grupos)

  • Números específicos: "5511999999999,5511888888888"
  • Compatibilidade para mencionar todos: "all"
  • Menção nativa a todos: inclua @all ou @todos diretamente no texto da mensagem
  • @todos é normalizado para @all antes do envio

• forward (boolean): Marca a mensagem como encaminhada no WhatsApp

  • Adiciona o indicador "Encaminhada" na mensagem
  • Exemplo: true

• track_source (string): Origem do rastreamento da mensagem

  • Identifica o sistema ou fonte que está enviando a mensagem
  • Útil para integrações (ex: "chatwoot", "crm", "chatbot")
  • Exemplo: "chatwoot"

• track_id (string): ID para rastreamento da mensagem

  • Identificador livre para acompanhar a mensagem em sistemas externos
  • Permite correlacionar mensagens entre diferentes plataformas
  • Nota: O sistema aceita valores duplicados - não há validação de unicidade
  • Use o mesmo ID em várias mensagens se fizer sentido para sua integração
  • Exemplo: "msg_123456789"

• async (boolean): Envia pela fila interna sem bloquear a requisição

  • Resposta 200 indica que a mensagem entrou na fila; o envio real pode falhar depois
  • Em caso de falha, pesquise em /message/find com status=failed

Diagnóstico de limites do WhatsApp

Em alguns casos, o WhatsApp pode recusar novas conversas por regras próprias de volume, qualidade ou limitação temporária.

Quando isso acontecer, a resposta de erro pode incluir:

• error_source: "whatsapp_server"
• provider: "whatsapp"
• provider_code: 463
• error_key
• message
• message_ptbr
• provider_message
• provider_message_ptbr
• diagnostics_endpoint
• details.new_chat_message_capping
• details.reachout_timelock

Para consultar o estado atual desses limites para a conta atualmente conectada, use:

• GET /instance/wa_messages_limits

Envio para Grupos

• number (string): Para enviar mensagem para grupo, use o ID do grupo que termina com @g.us
  • Exemplo: "120363012345678901@g.us"
  • Como obter o ID do grupo:
    • Use o chatid do webhook recebido quando alguém envia mensagem no grupo
    • Use o endpoint GET /group/list para listar todos os grupos e seus IDs

Placeholders Disponíveis

Campos textuais das operações de envio que documentam esse recurso aceitam os placeholders abaixo:

Campos de Nome

• {{name}}: Nome consolidado do chat, usando a primeira opção disponível:

  1. Nome do lead (lead_name)
  2. Nome completo do lead (lead_fullName)
  3. Nome do contato no WhatsApp (wa_contactName)
  4. Nome do perfil do WhatsApp (wa_name)

• {{first_name}}: Primeira palavra válida do nome consolidado (mínimo 2 caracteres)

Campos do WhatsApp

• {{wa_name}}: Nome do perfil do WhatsApp
• {{wa_contactName}}: Nome do contato como salvo no WhatsApp

Campos do Lead

• {{lead_name}}: Nome do lead
• {{lead_fullName}}: Nome completo do lead
• {{lead_personalid}}: ID pessoal (CPF, CNPJ, etc)
• {{lead_email}}: Email do lead
• {{lead_status}}: Status atual do lead
• {{lead_notes}}: Anotações do lead
• {{lead_assignedAttendant_id}}: ID do atendente designado

Campos Personalizados

Os 20 campos personalizados são acessíveis somente por {{lead_field01}} até {{lead_field20}}. /instance/updateFieldsMap configura o rótulo de cada campo, mas não cria um novo nome de placeholder. Por exemplo, mesmo que lead_field01 receba o rótulo empresa, use {{lead_field01}}, não {{empresa}}.

Exemplo de Uso

Olá {{first_name}}! Empresa: {{lead_field01}}.
Seu email {{lead_email}} está correto?

💡 Dica: Use /chat/find para buscar dados do chat e ver os campos disponíveis antes de enviar mensagens com placeholders.