Enviar mensagens pela API

Preparar uma chamada segura

1. 1

   Acesse Configuração > API e confirme qual credencial será usada pelo sistema consumidor.

2. 2

   Copie a URL base e o ApiID diretamente da documentação do seu ambiente.

3. 3

   Envie o token no cabeçalho Authorization com o esquema Bearer e use Content-Type application/json nas requisições com corpo JSON.

4. 4

   Use um contato controlado e envie somente uma mensagem na primeira validação.

5. 5

   Registre horário, método, rota e externalKey sem registrar o token nem dados pessoais completos.

Escolher a rota de mensagem

• Texto: POST /v2/api/external/{ApiID}, com os campos publicados body, number, externalKey, isClosed e validateNumber.
• Arquivo por endereço público: POST /v2/api/external/{ApiID}/url, com mediaUrl, body, number, externalKey, isClosed e validateNumber.
• Arquivo em Base64: POST /v2/api/external/{ApiID}/base64, com body, number, base64Data, mimeType, fileName, isClosed e validateNumber.
• Áudio: POST /v2/api/external/{ApiID}/voice, com audio, number, externalKey e isClosed.
• Localização: POST /v2/api/external/{ApiID}/sendLocation, com número, coordenadas e os dados descritivos publicados no formulário da rota.
• Contato: POST /v2/api/external/{ApiID}/sendVcard, com number, contact, ticketId e externalKey.
• Pesquisa no histórico: GET /v2/api/external/{ApiID}/searchMessages, filtrando por ticketId, searchParam, page e limit.
• Consulta de mensagem oficial: GET /v2/api/external/{ApiID}/getMessageByMessageId, informando o messageId retornado pelo canal.

Entender os campos que mudam o resultado

• number deve conter DDI, DDD e número somente no formato aceito pelo canal e pela documentação interativa do ambiente.
• externalKey é uma chave única criada pelo sistema consumidor e não pode se repetir. Ela não deve ser tratada como garantia automática de repetição segura.
• isClosed define se o atendimento será encerrado depois do envio; mantenha false durante o teste quando o objetivo for continuar a conversa.
• validateNumber usa true como padrão documentado. Com false, o número é usado como recebido, sem a normalização do nono dígito brasileiro; confirme a necessidade no canal oficial.
• mediaUrl precisa estar acessível ao serviço e o arquivo deve respeitar os formatos e limites do canal.
• mimeType e fileName precisam corresponder ao conteúdo real enviado em Base64.

Exemplo conceitual para texto: envie POST para <URL_BASE>/v2/api/external/<API_ID>, use Authorization: Bearer <TOKEN> e um corpo fictício com body, number, externalKey, isClosed e validateNumber. Substitua os marcadores somente no sistema consumidor; nunca publique valores reais em documentos ou capturas.

Respeitar a janela do canal oficial

Mensagens livres no canal oficial dependem da janela de atendimento. Quando a janela estiver encerrada, retome a conversa com um template aprovado e use a rota de template indicada na documentação interativa da sua versão.

• POST .../template envia o template conforme o contrato publicado na rota.
• POST .../templateBody e POST .../templateMarketingBody atendem variações de corpo confirmadas na referência interativa.
• Valide nome, idioma, variáveis, categoria e aprovação antes do primeiro teste.

Validar o resultado e solucionar falhas

1. 1

   Envie uma única requisição para o contato de teste.

2. 2

   Guarde o estado HTTP, o horário e a externalKey em um log protegido.

3. 3

   Abra o ticket correspondente e confirme conteúdo, canal, status e horário.

4. 4

   Em caso de timeout, consulte o ticket antes de decidir por uma nova tentativa.

5. 5

   Somente repita o envio quando o sistema consumidor tiver reconciliado o resultado anterior.

• Autenticação recusada: confira esquema Bearer, token ativo, URL base e ApiID da mesma credencial.
• Número inválido: não envie identificador de visitante, WebChat ou ticket no campo number.
• Ticket encerrado inesperadamente: revise isClosed.
• Mídia recusada: confirme formato, MIME, nome, tamanho e acesso ao arquivo.
• Mensagem duplicada: procure retentativas automáticas e consumidores concorrentes antes de reenviar.