Incorporar Atendimento em Outro Sistema

Sua equipe trabalha em outro sistema e precisa trocar de tela toda vez que vai responder um cliente? Com o Token de Validação, a tela de um atendimento aparece dentro do seu sistema, como uma janela aberta para aquela conversa, sem o operador precisar entrar na plataforma.

Essa janela se chama iframe: um pedaço de página que mostra outra página dentro dela. Para usar, basta montar um link e colar um código no seu sistema.

Ideal para:

Atendimento no sistema da equipe: mostra a conversa na mesma tela em que o operador já trabalha.

Abertura direta pelo número do ticket: leva àquela conversa sem passar pelas listas da plataforma.

Como gerar o Token de Validação

Acesse o menu Configurações → Opções, seção Webhooks | Eventos. Essa tela é do perfil Administrador.

Token de Validação (incorporar atendimento): é a senha que libera o link do atendimento. Com o campo vazio, o recurso fica desligado e todo link é recusado. Se a empresa não usa o atendimento incorporado, deixe o campo vazio. Para desligar um token que já existe, apague o campo: ao sair dele, a mudança já fica gravada.

GERAR: cria um token novo e já grava, sem botão de salvar. O token anterior para de funcionar na hora, e os links montados com ele passam a ser recusados.

Trate o Token de Validação como senha. Com ele e o ID de um Administrador, qualquer pessoa abre os atendimentos da empresa e responde em nome desse operador. Se desconfiar que vazou, clique em GERAR.

Como montar o link do atendimento

O link tem sempre este formato. Copie e troque as quatro partes em MAIÚSCULAS:

https://ENDERECO_DO_PAINEL/embed/ticket/NUMERO_DO_TICKET?token=SEU_TOKEN&userId=ID_DO_OPERADOR

ENDERECO_DO_PAINEL: o endereço em que você entra na plataforma, o mesmo que aparece na barra do navegador.

NUMERO_DO_TICKET: o número entre parênteses no topo da conversa, ao lado do nome do contato. Em Maria Silva (417) | #755, o ticket é 417. O #755 é o protocolo, que é outro número. Se o nome aparecer cortado, feche o painel Informações.

SEU_TOKEN: o Token de Validação que você gerou.

ID_DO_OPERADOR: no menu Equipe, o card de cada pessoa mostra o ID. É com esse operador que a conversa abre, e o que for respondido ali fica em nome dele.

Exemplo preenchido, para o ticket 417 e o operador de ID 18:

https://ENDERECO_DO_PAINEL/embed/ticket/417?token=SEU_TOKEN&userId=18

Para testar, abra uma janela anônima no navegador e cole o link na barra de endereço. A conversa deve abrir sem pedir login.

Como colocar a conversa no seu sistema

Cole este código no HTML da página, no lugar em que a conversa deve aparecer, e troque o endereço pelo link que você montou:

<iframe credentialless allow="microphone; clipboard-write" src="https://ENDERECO_DO_PAINEL/embed/ticket/417?token=SEU_TOKEN&userId=18" width="100%" height="700" style="border:0"></iframe>

width: a largura da janela. 100% ocupa todo o espaço disponível.

height: a altura da janela, em pixels. Com 700, a conversa e a caixa de mensagem aparecem inteiras.

credentialless: mantém a conversa separada do login que já estiver aberto no navegador. Deixe esse atributo no código.

allow: libera o microfone para gravar áudio e a cópia de texto dentro da conversa. Sem ele, gravar áudio não funciona.

Quando a página é gerada por programação, este exemplo em PHP monta o mesmo código:

<?php

$painel   = 'https://ENDERECO_DO_PAINEL';
$token    = 'SEU_TOKEN';
$ticket   = 417; // número do ticket
$operador = 18;  // ID do operador

$link = $painel . '/embed/ticket/' . $ticket . '?token=' . urlencode($token) . '&userId=' . $operador;

echo '<iframe credentialless allow="microphone; clipboard-write" src="' . htmlspecialchars($link) . '" width="100%" height="700" style="border:0"></iframe>';

O link leva o Token de Validação junto. Quem vê o código da página vê o token. Use o iframe só em página protegida por login do seu sistema, nunca em site público.

Do seu sistema até o link

O seu sistema conhece o cliente pelo telefone, não pelo número do ticket. Não é preciso ligar cada contato à mão: com a API da plataforma, o seu sistema acha o ticket pelo telefone, cria o que faltar e monta o link na hora, em até três comandos.

Os comandos usam o token de uma Conexão no lugar de TOKEN_DA_CONEXAO. Com o Token da Empresa, a busca pelo telefone pede também o campo whatsappId, com o ID da Conexão. O Token de Validação não funciona na API.

Buscar os tickets pelo telefone

Troque o número do exemplo pelo telefone do cliente, com o código do país e o DDD, só os dígitos:

curl -X GET "https://api.talkz.ai/api/contacts/alltickets" -H "Authorization: Bearer TOKEN_DA_CONEXAO" -H "Content-Type: application/json" -d '{"number":"5511999998888"}'

A resposta é a lista de tickets do contato. Em cada ticket, os campos que importam para o link:

• id — o número do ticket, que vai no link.
• whatsappId — a Conexão do ticket.
• status — pending quando está aguardando, open em atendimento, closed encerrado.
• queueId — o Setor do ticket, vazio quando ele não está em nenhum Setor.

Criar o contato, se a busca não achou

curl -X POST "https://api.talkz.ai/api/contacts" -H "Authorization: Bearer TOKEN_DA_CONEXAO" -H "Content-Type: application/json" -d '{"name":"Maria Silva","number":"5511999998888"}'

A resposta traz o id do contato novo. Se o telefone já estiver cadastrado, o contato não é duplicado: a resposta traz alreadyExists e, em existingContact, o contato que já existia, com o id dele.

Abrir o ticket, se o contato ainda não tem

Troque 123 pelo id do contato:

curl -X POST "https://api.talkz.ai/api/tickets/createTicketAPI" -H "Authorization: Bearer TOKEN_DA_CONEXAO" -H "Content-Type: application/json" -d '{"contactId":123}'

A resposta traz o ticket, e o número dele vem no campo id. Abrir o ticket pela API não envia nenhuma mensagem ao cliente.

Com o número do ticket e o ID do operador, o seu sistema monta o link no formato https://ENDERECO_DO_PAINEL/embed/ticket/NUMERO_DO_TICKET?token=SEU_TOKEN&userId=ID_DO_OPERADOR.

Outros jeitos de pegar os números

Pelos webhooks: quando o seu sistema já recebe os webhooks da Conexão ou do Setor, o número do ticket vem no campo ticketData.id, sem precisar buscar pelo telefone.

ID do operador: o comando abaixo lista a equipe com o id de cada pessoa. Troque TOKEN_DA_API pelo token de uma Conexão ou pelo Token da Empresa.

curl "https://api.talkz.ai/api/company/users" -H "Authorization: Bearer TOKEN_DA_API"

Cuidados ao buscar e criar pela API

Telefone com os mesmos dígitos do cadastro: a busca só acha o contato quando o telefone tem os mesmos dígitos gravados na plataforma. Se a resposta voltar com erro 400, tente o número com e sem o 9 depois do DDD.

Mais de um ticket por contato: o contato pode ter tickets em várias Conexões, e mais de um na mesma. Escolha pelo whatsappId o ticket da Conexão em que a sua equipe atende.

Ticket aberto pela API fica sem Setor: o Administrador e o Supervisor abrem o link na hora. O operador de perfil Usuário só abre depois que o ticket é colocado num Setor dele.

Abrir o ticket de novo devolve o mesmo: repetir o comando de abrir o ticket não cria outro. Se o ticket estiver encerrado, ele continua encerrado e sem Setor, por isso só Administrador e Supervisor abrem o link.

Faça essas chamadas no servidor do seu sistema, nunca no navegador. Com o token da Conexão, qualquer pessoa lê os atendimentos e envia mensagens por ela. No código de uma página, o token fica à vista de quem abrir.

O que o operador vê no atendimento incorporado

A tela mostra só aquela conversa, com a caixa de mensagem e as ações do topo do atendimento, sem o menu lateral e sem as listas da plataforma.

Ticket aguardando: clique em ACEITAR e recarregue a página para liberar a caixa de mensagem. O ticket passa a ser do operador do link.

Mensagens novas: recarregue a página para ver o que acabou de chegar do cliente.

Respostas: são enviadas e registradas em nome do operador do link.

Tela aberta há muito tempo: o acesso vale por 2 horas. Depois disso, recarregue a página antes de responder.

Quem consegue abrir cada ticket

O link respeita o perfil e os Setores do operador informado nele:

Administrador e Supervisor: abrem qualquer ticket da empresa.

Usuário: abre os tickets dos Setores dele, mesmo os que estão com outro operador.

Usuário convidado para a conversa: abre aquele ticket, mesmo sem ser do Setor.

Ticket encerrado: fica sem Setor, por isso só Administrador e Supervisor abrem.