sendMessageByTicket permite que você responda a qualquer conversa usando apenas o ID do ticket, sem precisar saber o canal subjacente ou o identificador do destinatário. Também é a única forma de enviar mensagens para conversas do Webchat e do Mercado Livre, que não possuem número de telefone endereçável nem ID externo persistente.
Visão Geral
Quando você já tem umticketId vindo de um payload de webhook ou de uma chamada de API anterior, não precisa saber o canal subjacente: o endpoint sendMessageByTicket resolve o canal pelo próprio atendimento e roteia a mensagem para a conversa correta. Por isso, o token de qualquer API ativa da sua empresa serve para responder conversas de qualquer canal (WhatsApp, Instagram, Messenger, Telegram, Webchat, E-mail, Hub Notificame e Mercado Livre), mesmo que a API tenha sido criada para outro canal.
Esta também é a única forma de enviar mensagens para conversas do Webchat e do Mercado Livre, já que esses canais não possuem número de telefone ou identificador persistente que você possa endereçar diretamente.
URL Base
Conceitos-Chave
reopen
Se o ticket estiver fechado no momento, você deve definir reopen: true para reabri-lo antes que a mensagem possa ser entregue. Enviar para um ticket fechado sem essa flag retorna um erro 409 ERR_TICKET_CLOSED.
isClosed
Defina isClosed: true para fechar automaticamente o ticket imediatamente após o envio da mensagem. É útil para enviar uma resposta final e arquivar a conversa na mesma requisição.
Janela de Idempotência do externalKey
O externalKey é opcional, mas recomendado. Se o mesmo valor de externalKey for enviado duas vezes dentro de 120 segundos, a segunda chamada é tratada como duplicada. Em vez de enviar novamente, a API retorna:
Uma Única Fonte de Mídia por Requisição
Cada requisição pode incluir no máximo uma das seguintes opções:media: um arquivo enviado comomultipart/form-datamediaUrl: uma URL de acesso público apontando para o arquivobase64Data: o conteúdo do arquivo codificado como uma string base64
Regras do mediaUrl
- Deve usar o esquema
httpouhttps. - Redirecionamentos não são seguidos.
- Hosts internos, privados ou loopback são bloqueados.
Enviar uma Mensagem de Texto
Responda a uma conversa aberta com uma mensagem de texto simples.Request
Chave de idempotência única gerada pelo seu sistema. A janela de deduplicação é de 120 segundos.
Defina como
true para reabrir um ticket fechado antes de enviar. Obrigatório se o ticket não estiver atualmente aberto ou pendente.Enviar um Arquivo via URL
Envie um arquivo de uma URL publicamente hospedada para um ticket existente.Request
URL de acesso público do arquivo. Deve usar
http ou https. Redirecionamentos e hosts privados não são permitidos.Enviar um Arquivo em Base64
Envie um arquivo codificado em base64 diretamente no corpo da requisição, sem necessidade de hospedagem externa. O corpo JSON, já com o base64, pode ter até 50 MB.Request
Tipo MIME do arquivo (obrigatório com
base64Data), por exemplo image/png ou application/pdf.Enviar um Arquivo via Multipart
Envie um arquivo diretamente do seu sistema usando uma requisiçãomultipart/form-data para o mesmo endpoint.
Resposta de Sucesso
Obtendo um ticketId a partir de Webhooks
A forma mais confiável de obter um ticketId é configurar um webhook no seu canal. Quando uma nova mensagem chega, o PanÐá Zap envia (POST) um payload para o seu endpoint que inclui o ID do ticket para todos os tipos de canal, inclusive e-mail. Se preferir não usar webhook, consulte periodicamente /listTickets e /showAllMessages, descritas em Tickets.
Para ativar os webhooks:
- Vá para Administração → Canais.
- No cartão do canal, abra o menu de três pontos e clique em Editar.
- Abra a seção Webhook do Canal e ative Habilitar Webhook do Canal.
- Preencha a URL de destino.
- Ative Mensagens recebidas e clique em Salvar alterações.
ticket.id de cada webhook recebido para usar com sendMessageByTicket quando precisar responder a essa conversa.
