Sobre
O Toolzz Chat permite dois tipos de integrações: Webhooks e aplicativos.
As integrações via webhooks permitem que diferentes sistemas se comuniquem em tempo real, enviando notificações ou dados entre eles automaticamente. Já os aplicativos personalizados oferecem a flexibilidade de adaptar funcionalidades específicas às necessidades únicas do seu negócio, melhorando a produtividade e a eficácia operacional.
Passo a passo
1º passo: no menu lateral, clique na opção de "Configurações", representada pelo ícone de uma engrenagem. Em seguida, clique na opção "Integrações".
Configurando Webhooks
Webhooks fornecem informações em tempo real sobre o que está acontecendo em sua conta. Eles são acionados por eventos como a criação de mensagens no Toolzz Chat. Você pode usar os webhooks para comunicar eventos com vários aplicativos, entre eles Toolzz Connect e Toolzz AI. Clique em Configurar para configurar seus webhooks.
É possível criar mais de um webhook para esta conta.
2º passo: clique no botão "Configurar" da opção "Webhooks".
3º passo: clique no botão "Adicionar novo webhook".
4º passo: preencha o formulário e depois clique em "Criar Webhook".
Digite uma URL válida para configurar um retorno de chamada.
Selecione o ou os eventos que deseja incluir.
Exemplo de Webhook:
{
"event": "message_created", // O nome do evento
"id": "1", // ID da mensagem
"content": "Olá", // Conteúdo da mensagem
"created_at": "2024-05-06 13:05:57 UTC", // Hora em que a mensagem foi enviada
"message_type": "incoming", // Este terá um tipo de entrada, saída ou modelo. O usuário do widget envia mensagens de entrada e o agente envia mensagens de saída para o usuário.
"content_type": "enum", // Este é um enum, pode ser input_select, cartões, formulário ou texto. O message_type será o modelo se content_type for um deles. O valor padrão é texto
"content_attributes": {} // Este será um objeto, valores diferentes são definidos abaixo
"source_id": "", // Este seria o ID externo se a caixa de entrada fosse uma integração com Twitter ou Facebook.
"sender": { // Isso forneceria os detalhes do agente que enviou esta mensagem
"id": "1",
"name": "Agente",
"email": "agente@example.com"
},
"contact": { // Isso forneceria os detalhes do usuário que enviou esta mensagem
"id": "1",
"name": "contact-name"
},
"conversation": { // Isso forneceria os detalhes da conversa
"display_id": "1", // Este é o ID da conversa que você pode ver no painel.
"additional_attributes": {
"browser": {
"device_name": "Macbook",
"browser_name": "Chrome",
"platform_name": "Macintosh",
"browser_version": "80.0.3987.122",
"platform_version": "10.15.2"
},
"referer": "<http://www.toolzzchat.com>",
"initiated_at": "Tue Jun 05 2024 18:37:38 GMT-0700 (Mountain Standard Time)"
}
},
"account": { // Isso forneceria os detalhes da conta
"id": "1",
"name": "ToolzzChat",
}
}
Eventos de webhook suportados no Toolzz Chat
Cada evento tem sua estrutura de carga baseada no tipo de modelo em que está atuando. A seção a seguir descreve os principais objetos que usamos no Toolzz Chat e seus atributos.
Objetos
Uma carga útil de evento pode incluir qualquer um dos objetos a seguir. Os vários tipos de objetos suportados pelo Toolzz Chat estão listados abaixo.
Conta
{
"id": "integer",
"name": "string"
}Caixa de entrada
{
"id": "integer",
"name": "string"
}Contato
{
"id": "integer",
"name": "string",
"avatar": "string",
"type": "contact",
"account": {
// <...Objeto de conta>
}
}Do utilizador
{
"id": "integer",
"name": "string",
"email": "string",
"type": "user"
}Conversação
{
"additional_attributes": {
"browser": {
"device_name": "string",
"browser_name": "string",
"platform_name": "string",
"browser_version": "string",
"platform_version": "string"
},
"referer": "string",
"initiated_at": {
"timestamp": "iso-datetime"
}
},
"can_reply": "boolean",
"channel": "string",
"id": "integer",
"inbox_id": "integer",
"contact_inbox": {
"id": "integer",
"contact_id": "integer",
"inbox_id": "integer",
"source_id": "string",
"created_at": "datetime",
"updated_at": "datetime",
"hmac_verified": "boolean"
},
"messages": ["Array of message objects"],
"meta": {
"sender": {
// Objeto de contato
},
"assignee": {
// Objeto de usuário
}
},
"status": "string",
"unread_count": "integer",
"agent_last_seen_at": "unix-timestamp",
"contact_last_seen_at": "unix-timestamp",
"timestamp": "unix-timestamp",
"account_id": "integer"
}Mensagem
{
"id": "integer",
"content": "string",
"message_type": "integer",
"created_at": "unix-timestamp",
"private": "boolean",
"source_id": "string / null",
"content_type": "string",
"content_attributes": "object",
"sender": {
"type": "string - contact/user"
// Objeto de usuário ou contato
},
"account": {
// Objeto de conta
},
"conversation": {
// Objeto de conversa
},
"inbox": {
// Objeto de caixa de entrada
}
}Um exemplo de carga útil do webhook
{
"event": "event_name"
// Atributos relacionados ao evento
}
Eventos de Webhooks
O Toolzz Chat oferece suporte aos seguintes eventos de webhook. Você pode assiná-los enquanto configura um webhook no painel ou usar a API.
conversa_criada
Este evento será acionado quando uma nova conversa for criada na conta. A carga útil do evento é a seguinte.
{
"event": "conversation_created"
// <...Atributos de conversa>
}
conversa_status_changed
Este evento será acionado quando o status da conversa for alterado.
Observação: se você estiver usando APIs de agent bot em vez de webhooks, esse evento ainda não será compatível.
{
"event": "conversation_status_changed"
// <...Atributos de conversa>
}
conversa_atualizada
Este evento será acionado quando houver alteração em algum dos atributos da conversa.
{
"event": "conversation_updated",
"changed_attributes": [
{
"<attribute_name>": {
"current_value": "",
"previous_value": ""
}
}
]
// <...Atributos de conversa>
}
mensagem_criada
Este evento será acionado quando uma mensagem for criada em uma conversa. A carga útil do evento é a seguinte.
{
"event": "message_created"
// <...Atributos de mensagem>
}
mensagem_atualizada
Este evento será acionado quando uma mensagem for atualizada em uma conversa. A carga útil do evento é a seguinte.
{
"event": "message_updated"
// <...Atributos de mensagem>
}
webwidget_triggered
Este evento será acionado quando o usuário final abrir o widget de chat ao vivo.
{
"id": ,
"contact": {
// <...Objeto de contato>
},
"inbox": {
// <...Objeto de caixa de entrada>
},
"account": {
// <...Objeto de conta>
},
"current_conversation": {
// <...Objeto de conversa>
},
"source_id": "string",
"event": "webwidget_triggered",
"event_info": {
"initiated_at": {
"timestamp": "date-string"
},
"referer": "string",
"widget_language": "string",
"browser_language": "string",
"browser": {
"browser_name": "string",
"browser_version": "string",
"device_name": "string",
"platform_name": "string",
"platform_version": "string"
}
}
}
5º passo: para editar um Webhook, clique no ícone de edição, representado pelo desenho de um quadro e um lápis, referente a ele.
Se quiser excluir um Webhook, clique no ícone com um "x" dentro de um círculo. Uma mensagem para confirmação da exclusão aparecerá. Confirme a ação para excluí-lo.
Configurando apps da Dashboard
Dashboard Apps permite que as organizações incorporem um aplicativo dentro da dashboard do Toolzz Chat para fornecer o contexto para agentes de suporte ao cliente. Este recurso permite criar uma aplicação independente e incorporá-la dentro da dashboard para fornecer informações do usuário, seus pedidos ou seu histórico de pagamentos anteriores.
Quando incorporado ao painel da plataforma, seu aplicativo obterá o contexto da conversa e do contato como um evento de janela. Implemente um ouvinte para o evento de mensagem em sua página para receber e utilizar esse contexto de forma eficaz.
6º passo: na página de integrações, clique no botão "Configurar" da opção "Apps da Dashboard".
7º passo: clique no botão "Adicionar um novo app da dashboard".
8º passo: preencha o formulário e depois clique em "Enviar".
Digite o nome do seu aplicativo.
Insira a URL na qual ele está hospedado.
❗Informações importantes
Quando terminar, uma nova aba com o nome que você deu ao aplicativo aparecerá na janela de conversa. Neste caso, são “Pedidos de Clientes”.
Ao clicar na nova aba, você poderá ver seu aplicativo buscando dados no painel do Toolzz Chat.
Recebendo dados do Toolzz Chat em seu aplicativo
O Toolzz Chat entregará o contexto da conversa e do contato como um evento de janela. Isso pode ser acessado em seu aplicativo implementando um ouvinte para o evento, conforme mostrado aqui:
window.addEventListener("message", function (event) {
if (!isJSONValid(event.data)) {
return;
}
const eventData = JSON.parse(event.data);
});
Solicitação sob demanda de dados do Toolzz Chat
Se precisar solicitar os dados da conversa sob demanda do Toolzz Chat, você pode enviar uma mensagem para a janela pai usando a API javascript postMessage .
Toolzz Chat estará ouvindo esta chave: chat-dashboard-app:fetch-info.
Exemplo
O código a seguir pode ser usado para consultar o aplicativo de painel. Toolzz Chat responderá a esta solicitação fornecendo a carga útil da conversa atualizada imediatamente.
window.parent.postMessage('chat-dashboard-app:fetch-info', '*')
// Você receberia uma mensagem no ouvinte de mensagem com a carga appContext.
Carga útil do evento
objeto de conversa
{
"meta": {
"sender": {
"additional_attributes":
"description": "string",
"company_name": "string",
"social_profiles": {
"github": "string",
"twitter": "string",
"facebook": "string",
"linkedin": "string"
}
},
"availability_status": "string",
"email": "string",
"id": "integer",
"name": "string",
"phone_number": "string",
"identifier": "string",
"thumbnail": "string",
"custom_attributes": "object",
"last_activity_at": "integer"
},
"channel": "string",
"assignee": {
"id": "integer",
"account_id": "integer",
"availability_status": "string",
"auto_offline": "boolean",
"confirmed": "boolean",
"email": "string",
"available_name": "string",
"name": "string",
"role": "string",
"thumbnail": "string"
},
"hmac_verified": "boolean"
},
"id": "integer",
"messages": [
{
"id": "integer",
"content": "Hello",
"inbox_id": "integer",
"conversation_id": "integer",
"message_type": "integer",
"content_type": "string",
"content_attributes": {},
"created_at": "integer",
"private": "boolean",
"source_id": "string",
"sender": {
"additional_attributes": {
"description": "string",
"company_name": "string",
"social_profiles": {
"github": "string",
"twitter": "string",
"facebook": "string",
"linkedin": "string"
}
},
"custom_attributes": "object",
"email": "string",
"id": "integer",
"identifier": "string",
"name": "string",
"phone_number": "string",
"thumbnail": "string",
"type": "string"
}
}
],
"account_id": "integer",
"additional_attributes": {
"browser": {
"device_name": "string",
"browser_name": "string",
"platform_name": "string",
"browser_version": "string",
"platform_version": "string"
},
"referer": "string",
"initiated_at": {
"timestamp": "string"
}
},
"agent_last_seen_at": "integer",
"assignee_last_seen_at": "integer",
"can_reply": "boolean",
"contact_last_seen_at": "integer",
"custom_attributes": "object",
"inbox_id": "integer",
"labels": "array",
"muted": "boolean",
"snoozed_until": null,
"status": "string",
"timestamp": "integer",
"unread_count": "integer",
"allMessagesLoaded": "boolean",
"dataFetched": "boolean"
}
objeto de contato
{
"additional_attributes": {
"description": "string",
"company_name": "string",
"social_profiles": {
"github": "string",
"twitter": "string",
"facebook": "string",
"linkedin": "string"
}
},
"availability_status": "string",
"email": "string",
"id": "integer",
"name": "string",
"phone_number": "+91 9000000001",
"identifier": "string || null",
"thumbnail": "+91 9000000001",
"custom_attributes": {},
"last_activity_at": "integer"
}
objeto currentAgent
{
"email": "string",
"id": "integer",
"name": "string"
}
Carga Final
{
"event": "appContext",
"data": {
"conversation": {
// <...Atributos de conversa>
},
"contact": {
// <...Atributos de contato>
},
"currentAgent": {
// <...Atributos do agente atual>
}
}
}9º passo: para editar um app da dashboard, clique no ícone de edição, representado pelo desenho de um quadro e um lápis, referente a ele.
Se quiser excluir um app da dashboard, clique no ícone com um "x" dentro de um círculo. Uma mensagem para confirmação da exclusão aparecerá. Confirme a ação para excluí-lo.
Pronto! Agora você já sabe como configurar e gerenciar integrações no Toolzz Chat.