Pular para o conteúdo principal
Toda conversa no PanÐá Zap é representada como um ticket. Use os endpoints abaixo para abrir tickets de forma programática, sincronizar seu status com sistemas externos, marcá-los com tags e roteá-los, anexar notas e fechá-los, tudo sem precisar acessar o painel. Todas as requisições exigem o cabeçalho Authorization: Bearer {BearerToken}.

Criar ticket

Abre um ticket (atendimento) com uma mensagem inicial. Funciona com canais WhatsApp e com o canal de e-mail (Webmail).
Para o canal de e-mail (Webmail), omita number e envie email (obrigatório) e channelId (o ID do canal Webmail). O channelId só pode ficar de fora quando a própria API do token for de um canal Webmail: com token de outro canal e sem channelId, a rota responde 400 ERR_NUMBER_REQUIRED. Opcionalmente, envie name, firstName e lastName, usados para criar o contato caso ele ainda não exista.
Para abrir o ticket já com um arquivo, envie esta mesma rota como multipart/form-data, com o arquivo no campo media e os demais campos como texto. Atenção: nos testes, com um ticket já aberto para o contato, a versão com arquivo abriu um segundo ticket em vez de reutilizar o existente.
Resposta: em caso de sucesso, data.message traz o texto Ticket create successfully seguido dos dados do ticket criado (id, status, protocol, contactId, whatsappId, userId, queueId, channel, createdAt) em formato JSON dentro do próprio texto, e data.error vem false. Para usar o ID do novo ticket, extraia-o desse texto ou consulte os tickets do contato com Exibir todos os tickets de um número.

Listar tickets

Retorna uma lista paginada de tickets filtrada pelos parâmetros fornecidos.

Exibir ticket por número

Retorna um ticket aberto (open) do contato informado. Tickets pendentes ou fechados não são considerados: se o contato não tiver ticket aberto, a rota responde 404. Se houver mais de um aberto, não há garantia de que venha o mais recente.

Exibir todos os tickets de um número

Retorna todos os tickets associados ao número de contato informado, independentemente do status.

Exibir ticket por ID


Exibir ticket para chatbot

Retorna o primeiro ticket do contato que tenha um fluxo de chatbot vinculado, independentemente do status: um ticket fechado com fluxo também é retornado, e um ticket aberto sem fluxo responde 404 com o erro ERR_TICKET_CHATFLOW_NOT_FOUND.

Atualizar informações do ticket

Atualize de uma vez o status, a fila, o fluxo de chatbot e as integrações de automação de um ticket.
queueId, userId e chatFlowId precisam existir na sua empresa. Caso contrário a rota responde 404 com ERR_QUEUE_NOT_FOUND, ERR_USER_NOT_FOUND ou ERR_CHATFLOW_NOT_FOUND, respectivamente. Os campos de integração (typebotStatus, lmStatus, chatgptStatus, dialogflowStatus, difyStatus e n8nStatus) aceitam true ou false (também "enabled" ou "disabled", e 1 ou 0). Qualquer outro valor responde 400 com ERR_INVALID_FIELD, e o nome do campo vem em field. A troca de fila, de atendente ou de fluxo feita por esta rota fica registrada no histórico do atendimento como uma mensagem de sistema (mediaType transfer, com dataJson.kind ticket_transfer), que nunca é enviada ao contato e aparece em Obter todas as mensagens de um ticket. Atendimento encerrado (antes ou depois da chamada) ou ainda sem mensagens não ganha o registro.

Atualizar fila do ticket

Define ou troca a fila de um ticket. Os IDs das filas saem de listQueues.
Só ticketId e queueId são lidos: para trocar o atendente ou o status, use Atualizar informações do ticket. Envie queueId como null para tirar a fila do ticket. A resposta traz o ticket sem as chaves do canal. A troca de fila fica registrada no histórico do atendimento como uma mensagem de sistema (mediaType transfer, com dataJson.kind ticket_transfer), que nunca é enviada ao contato e aparece em Obter todas as mensagens de um ticket. Não ganha o registro o atendimento encerrado, ainda sem mensagens ou que já estava na mesma fila.

Atualizar canal do ticket

Move um ticket para um canal (conexão WhatsApp) diferente, mantendo o histórico da conversa.
A troca de canal fica registrada no histórico do atendimento como uma mensagem de sistema (mediaType transfer, com dataJson.kind ticket_transfer), que nunca é enviada ao contato e aparece em Obter todas as mensagens de um ticket. Atendimento encerrado ou ainda sem mensagens não ganha o registro.

Adicionar tag ao ticket

Adicionar uma única tag:
Adicionar várias tags de uma vez:

Remover tag do ticket

Para remover várias tags de uma vez, envie tagIds (ex.: [1, 2, 3]) no lugar de tagId.

Definir tag do ticket (substituição única)

Substitui as tags do contato do ticket pela tag informada.
As demais tags do contato são removidas, e o efeito vale para todos os tickets desse contato. Para acrescentar uma tag sem remover as outras, use Adicionar tag ao ticket.
Erros:
  • ticketId e tag precisam ser IDs numéricos: senão a rota responde 400 ERR_INVALID_TICKET_ID ou ERR_INVALID_FIELD (com o nome do campo em field).
  • Ticket ou tag que não existe na sua empresa: 404 ERR_TICKET_NOT_FOUND ou ERR_TAG_NOT_FOUND, sem alterar nada.

Status de presença (digitando / gravando)

Sinaliza ao contato que um agente está digitando, gravando um áudio ou pausou a interação (o mesmo indicador visual “digitando…” usado nativamente pelo WhatsApp).
Nos canais oficiais (WhatsApp Business oficial e 360dialog), só typing funciona, e a Meta marca como lida a última mensagem recebida do contato. recording e paused nesses canais, e qualquer estado no canal Gupshup, respondem 400 com ERR_PRESENCE_NOT_SUPPORTED.

Obter todas as mensagens de um ticket

Obtenha o histórico completo de mensagens de um determinado ticket.
Informe o ID do ticket no campo ticket (ou em ticketId, com o mesmo valor). Sem o ID, a rota responde 400 com ERR_MISSING_TICKET. A lista traz também as mensagens de sistema, que nunca foram enviadas ao contato. Identifique-as pelo mediaType: Nas divisórias novas, dataJson vem como texto com um JSON dentro (converta antes de ler), com kind ticket_transfer, a origem, o destino e o autor da troca. O autor vem nulo nas transferências automáticas, e as divisórias antigas vêm sem dataJson.
Se o seu sistema reproduz a conversa ou conta as mensagens trocadas com o contato, filtre essas mensagens de sistema pelo mediaType.

Pesquisar mensagens dentro de um ticket


Criar nota interna

Notas internas são visíveis apenas para os agentes e nunca são enviadas ao contato.

Listar notas internas


Atualizar nota interna


Pausa de ticket

Use a pausa para interromper temporariamente um ticket, para controle de SLA: por exemplo, enquanto aguarda a resposta de um cliente ou a conclusão de um processo interno. Iniciar pausa:
Encerrar pausa:
Nenhum corpo de requisição é necessário para encerrar uma pausa. Erros de iniciar e encerrar pausa: Consultar histórico de pausas:
Retorna todas as pausas registradas para o ticket informado, incluindo motivo, início e término de cada uma.

Enviar avaliação de satisfação

Envia a pesquisa de satisfação para o contato de um ticket e registra a avaliação como pendente. A nota que o cliente responder é capturada automaticamente. A rota respeita o modo de avaliação configurado na sua conta (escala nativa ou link externo) e recusa grupos e canais sem suporte.
A resposta traz ticketId, contactId, evaluationId (a avaliação pendente registrada) e mode (o modo usado, ex.: native).

Listar avaliações de satisfação

Retorna o histórico paginado das avaliações de satisfação.

Compartilhamento de ticket

Compartilhe um ticket com outros usuários da sua equipe: é o mesmo recurso Compartilhar ticket da tela de atendimento. Cada ticket aceita um único compartilhamento; repetir a chamada responde 400. Criar compartilhamento:
Consultar compartilhamento:
Se o ticket não tiver compartilhamento criado, a rota responde 404 ERR_TICKET_SHARE_NOT_FOUND.