Webhook de atribuição de agente

Como funciona?

Quando uma conversa chega a um bloco de Métodos de transferência configurado com o destino API, o Treble envia uma requisição POST ao endpoint que você configurou, com as informações do contato e da conversa. O seu serviço decide qual agente deve atendê-la e o devolve na resposta. O Treble atribui a conversa a esse agente. Se o seu serviço não responder a tempo, ou o agente que você devolver não puder receber a conversa, o Treble aplica o método de reserva da sua empresa para que a conversa nunca fique sem atribuição.

Este webhook não é configurado na central de webhooks, mas dentro do próprio bloco no editor de conversas. Assim, cada bloco pode chamar um endpoint diferente.

Configurar o bloco

Aprenda a configurar a URL e a autenticação a partir do editor de conversas.

Autenticação

No bloco você pode escolher entre duas opções:

Sem autenticação — o Treble chama o seu endpoint sem credenciais.
Token / API Key — o Treble envia o token que você configurou no header Authorization:

Authorization: Bearer SEU_TOKEN

Use sempre https:// e configure um token. Assim o seu endpoint pode verificar que a chamada vem efetivamente do Treble.

A requisição que o Treble envia

O Treble faz um POST com um corpo JSON que contém o contexto do contato e da conversa.

{
  "company_id": 1234,
  "survey_user_id": 567890,
  "contact": {
    "treble_id": "5215512345678",
    "name": "Andrea Soto",
    "country_code": "52",
    "cellphone": "5512345678",
    "business_scope_id": "1029384756",
    "username": null
  },
  "crm_type": "salesforce",
  "crm_objects": [
    { "entity": "Contact", "id": "0035f00000ABCDEqAO" },
    { "entity": "Account", "id": "0015f00000FGHIJqAO" }
  ],
  "channel": {
    "phone_number_id": "1234567890"
  },
  "metadata": {
    "poll_id": 4321,
    "node_id": "a1b2c3",
    "tag": "Comercial",
    "language": "es"
  }
}

Campo	Descrição
`company_id`	Identificador da sua empresa no Treble.
`survey_user_id`	Identificador da sessão do contato na conversa.
`contact`	Informações do contato que está na conversa.
`crm_type`	CRM com o qual a sua conta está integrada, por exemplo `salesforce` ou `hubspot`. É `null` se não houver integração.
`crm_objects`	Registros do CRM associados ao contato.
`channel.phone_number_id`	Identificador da linha de WhatsApp que recebeu a conversa.
`metadata`	Contexto do fluxo e do bloco que originou a chamada: `poll_id`, `node_id`, `tag` e `language`.

cellphone e country_code podem chegar como null para contatos que só existem como usuário da Meta. Nesse caso, use business_scope_id ou username para identificar o usuário.

Identificadores do CRM

Quando a sua conta tem uma integração de CRM, a requisição inclui os identificadores do contato no seu CRM para que você possa decidir com base no registro; por exemplo, consultar o proprietário do registro e devolver esse agente.

crm_type — o CRM com o qual a sua conta está integrada. É null se a conta não tiver integração.
crm_objects — os registros do CRM associados ao contato. Cada um traz o seu entity (o tipo de objeto no CRM, por exemplo Contact, Account ou Lead) e o seu id (o identificador do registro no seu CRM). Um contato associado a vários objetos do Salesforce traz uma entrada por objeto; em outros CRMs há uma única entrada. Um array vazio significa que o contato ainda não está associado a nenhum registro.

A resposta que você deve devolver

Responda com 200 e um corpo JSON que identifique o agente. Você pode fazê-lo por email (recomendado) ou por id:

{
  "agent_email": "andrea.soto@suaempresa.com"
}

{
  "agent_id": 4567
}

agent_email — o email do agente tal como está registrado no Treble. É a opção recomendada porque não depende dos identificadores internos do Treble.
agent_id — o identificador do agente no Treble.

O agente que você devolver deve estar ativo. Para conhecer os agentes disponíveis na sua conta —e os valores exatos de email e id que você deve devolver— use o endpoint de obter os agentes da sua empresa.

O seu endpoint deve responder em menos de 10 segundos. Se exceder, devolver um código diferente de 200, ou devolver um agente que não pode receber a conversa, o Treble aplica o método de reserva configurado na plataforma principal.

Exemplo de implementação

Um endpoint mínimo em Node.js que devolve um agente de acordo com o contato:

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhooks/on-agent-assignation', (req, res) => {
  // Verifica que a chamada vem do Treble
  if (req.header('Authorization') !== `Bearer ${process.env.TREBLE_TOKEN}`) {
    return res.sendStatus(401);
  }

  const { contact, crm_type, crm_objects, metadata } = req.body;

  // Sua lógica para escolher o agente: round robin, idioma,
  // proprietário no CRM, segmento, etc.
  const agentEmail = escolherAgente(contact, crm_objects, metadata);

  // Devolve o agente por email (recomendado) ou por id
  res.json({ agent_email: agentEmail });
});

app.listen(3000, () => {
  console.log('Servidor escutando na porta 3000');
});

Introdução à API

API

Webhooks

Editor

Guias e Tutoriais

Webhook de atribuição de agente

Como funciona?

Configurar o bloco

Autenticação

A requisição que o Treble envia

Identificadores do CRM

A resposta que você deve devolver

Exemplo de implementação

Próximos passos

Referência do endpoint

Obter os agentes

​Como funciona?

Configurar o bloco

​Autenticação

​A requisição que o Treble envia

​Identificadores do CRM

​A resposta que você deve devolver

​Exemplo de implementação

​Próximos passos

Referência do endpoint

Obter os agentes

Como funciona?

Autenticação

A requisição que o Treble envia

Identificadores do CRM

A resposta que você deve devolver

Exemplo de implementação

Próximos passos