# 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.