Pular para o conteúdo principal

Contexto da Turn.io

info

Esta API de contexto está atualmente na versão 1.0.0-alpha. Esta API ainda está sujeita a mudanças à medida que os casos de uso se cristalizam.

O contexto da Turn.io automaticamente apresenta informações específicas para a conversa em andamento, provenientes de sistemas integrados por meio da API de integrações. O contexto da Turn.io não é armazenado; ele é um sistema em tempo real. À medida que as conversas acontecem, as integrações são consultadas para obter informações suplementares sobre os membros da conversa que podem ser relevantes para atingir os objetivos da conversa. Essas informações são exibidas em tempo real na Turn.io.

Biblioteca de Integração da Turn.io

Lançamos uma biblioteca em Javascript para ajudar no desenvolvimento de integrações do Turn.io.

Ela está disponível no GitHub em turnhub/turnio-integration ou você pode instalá-la com:

$ npm install @turnio/integration
$ yarn install @turnio/integration

Abaixo está um exemplo de integração que faz o seguinte:

  1. Exibe uma tabela e uma lista ordenada no painel de detalhes do contexto.
  2. Sugere conteúdo de redefinição de senha na caixa de resposta.
  3. Expõe um item de menu que permite alterar um idioma.
info

Integrações construídas com @turnio/integration podem ser executadas como funções em nuvem sem servidor em plataformas como Google Cloud Functions e similares.

const TurnIntegration = require("@turnio/integration");

const app = new TurnIntegration(process.env.SECRET)
  .context("Idioma", "table", ({ chat, messages }) => ({
    Idioma: "Inglês",
    Confiança: "Muito alta",
  }))
  .context("Uma lista de coisas", "ordered-list", ({ chat, messages }) => ["primeiro item", "segundo item", "terceiro item"])
  .suggest(({ chat, messages }) => [
    {
      type: "TEXT",
      title: "Redefinir senha",
      body: "Para redefinir sua senha, clique no link na página de login.",
      confidence: 0.4,
    },
  ])
  .action(({ chat, messages }) => [
    {
      description: "Alterar idioma",
      payload: {
        realmente: "sim",
      },
      options: {
        afr_ZA: "Africâner",
        eng_ZA: "Inglês",
        zul_ZA: "Zulu",
      },
      callback: ({ message, option, payload: { realmente } }, resp) => {
        console.log({ message, option, realmente });
        resp.setHeader("X-Turn-Integration-Refresh", "true");
        return { ok: "concluído" };
      },
    },
  ])
  .serve();

const port = process.env.PORT || 3000;

app.listen(port, () => console.log(`Aplicação de exemplo ouvindo na porta ${port}!`));

Handshake​

{
  "version": "1.0.0-alpha",
  "capabilities": {
    "actions": True,
    "suggested_responses": True,
    "context_objects": [
      {
        "title": "O título",
        "code": "details",
        "type": "table"
      }
    ]
  }
}

O handshake precisa ser realizado após a configuração da integração. Este é um chamado para a URL de contexto com um parâmetro de consulta handshake configurado como verdadeiro.

Os objetos de contexto da Turn.io podem ser de dois tipos: ordered-list ou table. A chave type é usada para identificá-los.

Todo objeto de contexto tem as seguintes chaves:

  • title, o título do bloco de contexto (por exemplo, Idioma ou Informações do Paciente)
  • type, ordered-list ou table
  • code, um identificador único para este conteúdo. Isso é usado para se referir ao bloco ao precisar atualizar uma informação na interface do usuário.

Os endpoints precisam fornecer uma chave context_objects que contenha uma chave para cada objeto de contexto configurado pelo handshake. A ordem dos objetos de contexto no painel de contexto é determinada pela ordem em que são fornecidos no retorno do handshake.

Um subconjunto limitado de Markdown é suportado para renderizar os valores passados como contexto. Os seguintes tipos são suportados:

Outros recursos de marcação, como imagens, títulos e listas, não são suportados.

Obtendo o contexto, ações e sugestões​

Quando uma conversa é carregada na interface do usuário, o navegador inicia uma solicitação para a integração pedindo uma atualização.

A integração irá acessar sua URL de integração com uma solicitação HTTP POST com o seguinte payload:

{
    "chat": {
        "owner": "<o número de telefone>",
        "state": "<o estado do chat>",
        ...
    },
    "messages": [{
        // as 10 mensagens mais recentes de entrada e saída
        // que fazem parte desta conversa
    }]
}

Atualizações de Contexto​

Ao receber a solicitação HTTP POST, você pode fornecer atualizações de objetos de contexto sob a chave context_objects, conforme os formatos abaixo.

Listas ordenadas​

{
  "version": "1.0.0-alpha",
  "context_objects": {
    "details": ["primeira vez", "*segundo item*", "~terceiro item~"]
  },
  "actions": {}
}

As listas ordenadas possuem uma lista como payload. Elas são automaticamente prefixadas com números, começando em 1. Não suportam nenhum tipo de aninhamento. A chave dentro de context_objects deve corresponder ao código no retorno do seu handshake.

Tabelas​

{
  "version": "1.0.0-alpha",
  "context_objects": {
    "details": {
      "Idioma": "[Tagalo](https://pt.wikipedia.org/wiki/L%C3%ADngua_tagalo)",
      "Confiança": "Muito Alta"
    }
  },
  "actions": {}
}

As tabelas possuem um dicionário como payload. A chave do dicionário é impressa em texto negrito, o valor do dicionário é impresso como normal. A chave dentro de context_objects deve corresponder ao código no retorno do seu handshake.

Respostas Sugeridas​

Ao receber a solicitação HTTP POST, você pode fornecer respostas sugeridas sob a chave suggested_responses, conforme o formato abaixo.

{
  "version": "1.0.0-alpha",
  "context_objects": {},
  "actions": {},
  "suggested_responses": [
    {
      "type": "TEXT",
      "title": "Redefinir Senha",
      "body": "Para redefinir sua senha, clique no link na página de login.",
      "confidence": 0.4
    }
  ]
}

As respostas sugeridas podem ser especificadas e serão exibidas em um menu de seleção acima da caixa de resposta. Elas serão ordenadas pela confiança.

As respostas sugeridas possuem as seguintes chaves:

  • type, o tipo de resposta
  • title, o título da resposta
  • body, o corpo da resposta
  • confidence, a pontuação de confiança desta resposta, usada para ordenar a lista

Ações​

Ao receber a solicitação HTTP POST, você pode fornecer ações personalizadas sob a chave actions, conforme o formato abaixo.

{
  "version": "1.0.0-alpha",
  "context_objects": {},
  "actions": {
    "change_language": {
      "description": "Alterar Idioma",
      "url": "/api/v1/turn/action",
      "payload": {
        "realmente": "sim"
      },
      "options": {
        "afr_ZA": "Africâner",
        "eng_ZA": "Inglês",
        "zul_ZA": "Zulu"
      }
    }
  }
}

As ações podem ser especificadas e serão exibidas em um menu suspenso acima do contexto. Elas enviarão o payload para a URL especificada na integração configurada quando clicadas.

As ações possuem as seguintes chaves:

  • description, o texto no menu suspenso
  • url, caminho da ação de integração
  • payload, payload que será enviado
  • options, (opcional) criará um menu aninhado e adicionará uma chave option ao payload com a opção selecionada.

Exemplo de payload JSON de callback

{
  "address": "+16315551003",
  "integration_uuid": "o-uuid-da-integração",
  "integration_action_uuid": "o-uuid-da-ação",
  "message": {
    // a mensagem usada para acionar esta ação
  },
  "option": "afr_ZA",
  "payload": {
    "realmente": "sim"
  }
}

Atualizando o contexto e ações​

Há uma boa chance de que você queira atualizar o contexto e as ações disponíveis na interface após concluir uma ação.

Atualização imediata​

Pode-se forçar uma atualização imediata do contexto e ações retornando o cabeçalho X-Turn-Integration-Refresh com o valor true.

Há um exemplo Turn.io Integration Demo que mostra como fazer isso. A aplicação de demonstração expõe uma ação de opt-in ou opt-out dependendo do estado. Uma vez que o opt-in é feito, o contexto é atualizado para mostrar o novo estado, e a ação é atualizada para exibir apenas a opção de opt-out.

Atualização atrasada​

Usando o integration_uuid e o integration_action_uuid, pode-se fazer uma solicitação HTTP ao endpoint de eventos da integração. Isso acionará o Turn.io para consultar sua integração e atualizar a interface com base nas informações retornadas.

Acessando o endpoint de eventos da integração

$ curl -X POST "https://whatsapp.turn.io/api/integrations/<seu-integration_uuid>/notify/finish" \
    -H "Content-Type: application/json" \
    -d '{
        "integration_action_uuid": "<seu-integration-action-uuid>"
    }'