Implementação de referência do EspoCRM

Este documento fornece um exemplo de integração com o Contact Center AI Platform (CCAI Platform) custom CRM usando o EspoCRM. O EspoCRM é um aplicativo de CRM sem custo financeiro e de código aberto que ajuda as empresas a gerenciar vendas, marketing e suporte ao cliente com uma interface personalizável. Ele oferece recursos como gerenciamento de contatos, rastreamento de atividades, automação de vendas e gerenciamento de inventário, com opções de auto-hospedagem ou implantação na nuvem.

Para configurar sua própria instância do EspoCRM, consulte a página de instalação do EspoCRM.

Antes de começar

Faça o seguinte:

• Configure seu firewall para permitir o tráfego da plataforma CCAI.

• Crie um usuário da API na sua instância do EspoCRM, por exemplo, google_integration_user. Para mais informações, consulte API na documentação do EspoCRM.

• Crie uma função na sua instância do EspoCRM com as ações Criar, Ler e Atualizar que acessam o seguinte:

  • Contatos: para encontrar ou criar chamadores
  • Casos: para pesquisar e registrar tíquetes

  Para mais informações, consulte Gerenciamento de papéis na documentação do ExpoCRM.

Importante: verifique se todos os endpoints de API configurados usam um certificado TLS válido.

Configurar uma conexão do EspoCRM com a plataforma CCAI

Para configurar uma conexão do EspoCRM com a CCAI Platform, siga estas etapas:

1. No portal da plataforma CCAI, clique em Configurações > Configurações do desenvolvedor. Se o menu Configurações não aparecer, clique em Menu.
2. Em Plataforma do agente, selecione CRM personalizado.
3. Clique no botão Mostrar CRM no portal da plataforma CCAI para ativar.
4. No campo URL de visualização, insira o URL a ser incorporado no portal da plataforma CCAI. Por exemplo, https://YOUR_ESPO_DOMAIN/#Case/view/{RECORD_ID}.
5. Em Método de pesquisa de CRM, selecione API genérica.
6. Para autenticar usando um cabeçalho personalizado, faça o seguinte:
   1. Na seção Método de autenticação, selecione Cabeçalho personalizado.
   2. Selecione Adicionar campo. A caixa de diálogo Adicionar campo aparece.
      1. No campo Chave do campo, digite X-Api-Key.
      2. No campo Valor do campo, insira a chave de API gerada quando você criou um usuário de API no EspoCRM.
      3. Clique em Salvar.
7. Para definir o URL de pesquisa do CRM, faça o seguinte:
   1. Na seção URL de pesquisa do CRM, no campo URL de pesquisa de registro, insira o URL para pesquisar um registro, por exemplo, https://YOUR_ESPO_DOMAIN/#Case/view/{RECORD_ID}.
   2. No campo URL de pesquisa de conta, insira o URL para pesquisar uma conta. Por exemplo, https://YOUR_ESPO_DOMAIN/#Contact/view/{ACCOUNT_ID}.
   3. Clique em Salvar. ## Configurar endpoints de API

Configure endpoints compatíveis com o EspoCRM para garantir que sua integração tenha os componentes para pesquisar contas (contatos) e registros (casos). Para mais informações sobre variáveis compatíveis, consulte Visão geral da API na documentação do EspoCRM.

Configurar endpoints de contas de API

Nesta seção, explicamos como configurar endpoints de contas de API.

Configurar um endpoint "Encontrar uma conta por consulta"

Para configurar o endpoint "Encontrar uma conta por consulta", siga estas etapas:

1. Na plataforma CCAI, clique em Configurações > Configurações do desenvolvedor. Se o menu Configurações não aparecer, clique em Menu.
2. No painel CRM, acesse a seção Conta da API.
3. Para Encontrar uma conta por endpoint de consulta, clique em Configuração. A página Configuração genérica do endpoint da API aparece.
4. No campo URL, insira o URL para pesquisar uma conta. Por exemplo, https://YOUR_ESPO_DOMAIN/api/v1/Contact.
5. Em Método, selecione GET.

6. Para configurar parâmetros de solicitação, faça o seguinte:

   1. Para configurar o primeiro parâmetro de solicitação, siga estas etapas:
      1. Selecione Adicionar campo. A caixa de diálogo Adicionar campo aparece.
      2. No campo Chave do campo, digite where[0][attribute].
      3. No campo Valor do campo, insira phoneNumber.
      4. Clique em Salvar.

   2. Para configurar o restante dos parâmetros de solicitação, repita as etapas anteriores usando as informações na tabela a seguir. Você já criou o primeiro parâmetro de solicitação.

      Chave de campo	Valor do campo
      where[0][attribute]	phoneNumber
      where[0][type]	equals
      where[0][value]	{PHONE_NUMBER}
      sortBy	createdAt
      asc	false

7. No campo Localização dos dados de resposta, insira data.list.

8. Clique em Salvar.

9. Clique em Voltar às configurações do desenvolvedor para retornar à página Configurações do desenvolvedor.

Configurar um endpoint "Encontrar uma conta por ID"

Para configurar o endpoint "Encontrar uma conta por ID", siga estas etapas:

1. No painel CRM, acesse a seção Conta da API.
2. Em Encontrar uma conta por ID do endpoint, clique em Configurar. A página Configuração genérica do endpoint da API aparece.
3. No campo URL, insira o URL para pesquisar uma conta. Por exemplo, https://YOUR_ESPO_DOMAIN/api/v1/Contact/{ACCOUNT_ID}.
   1. Em Método, selecione GET.
4. Defina o Local dos dados de resposta como data.
5. Clique em Salvar.
6. Clique em Voltar às configurações do desenvolvedor para retornar à página Configurações do desenvolvedor.

Configurar um endpoint "Criar uma conta"

Para configurar o endpoint "Criar uma conta", siga estas etapas:

1. No painel CRM, acesse a seção Conta da API.
2. Para Criar um endpoint de conta, clique em Configuração. A página Configuração genérica do endpoint da API aparece.
3. No campo URL, insira o URL para pesquisar uma conta. Por exemplo, https://YOUR_ESPO_DOMAIN/api/v1/Contact.
4. Em Método, selecione POST.

5. Para configurar Parâmetros de solicitação, faça o seguinte:

   1. Para configurar o primeiro parâmetro de solicitação, siga estas etapas:
      1. Em Parâmetros da solicitação, clique em Adicionar campo. A caixa de diálogo Adicionar campo aparece.
      2. No campo Chave do campo, digite phoneNumber.
      3. No campo Valor do campo, insira {PHONE_NUMBER}.
      4. Clique em Salvar.

   2. Para configurar o restante dos parâmetros de solicitação, repita a etapa anterior usando as informações na tabela a seguir. Você já criou o primeiro parâmetro de solicitação.

      Chave de parâmetro	Valor do parâmetro
      phoneNumber	{PHONE_NUMBER}
      firstName	New Caller
      lastName	{CALL_ID}
      name	New Caller {CALL_ID}

6. Defina o Local dos dados de resposta como data.

7. Defina o Local do ID do objeto como id.

8. Clique em Salvar.

9. Clique em Voltar às configurações do desenvolvedor para retornar à página Configurações do desenvolvedor.

Configurar um endpoint de atualização de conta

Para configurar o endpoint "Atualizar uma conta", siga estas etapas:

1. No painel CRM, acesse a seção Conta da API.
2. Para Atualizar um endpoint da conta, clique em Configuração. A página Configuração genérica do endpoint da API aparece.
3. No campo URL, insira o URL para pesquisar uma conta. Por exemplo, https://YOUR_ESPO_DOMAIN/api/v1/Contact.
4. Em Método, selecione PUT.

5. Para configurar Parâmetros de solicitação, faça o seguinte:

   1. Para configurar o primeiro parâmetro de solicitação, siga estas etapas:
      1. Em Parâmetros da solicitação, clique em Adicionar campo. A caixa de diálogo Adicionar campo aparece.
      2. No campo Chave do campo, digite contactId.
      3. No campo Valor do campo, insira {PHONE_NUMBER}.
      4. Clique em Salvar.

   2. Para configurar o restante dos parâmetros de solicitação, repita a etapa anterior usando as informações na tabela a seguir. Você já criou o primeiro parâmetro de solicitação.

      Chave de parâmetro	Valor do parâmetro
      contactId	{PHONE_NUMBER}
      phoneNumber	New Caller

6. Defina o Local dos dados de resposta como data.

7. Clique em Salvar.

8. Clique em Voltar às configurações do desenvolvedor para retornar à página Configurações do desenvolvedor.

Configurar endpoints de registros de API

Nesta seção, explicamos como configurar endpoints de registros de API.

Configurar um endpoint "Encontrar um registro por consulta"

Para configurar o endpoint "Encontrar um registro por consulta", siga estas etapas:

1. No painel CRM, acesse a seção Registro da API.
2. Em Encontrar um registro por endpoint de consulta, clique em Configuração. A página Configuração genérica do endpoint da API aparece.
3. No campo URL, insira o URL para pesquisar uma conta. Por exemplo, https://YOUR_ESPO_DOMAIN/api/v1/Case.
4. Em Método, selecione GET.

5. Para configurar Parâmetros de solicitação, faça o seguinte:

   1. Para configurar o primeiro parâmetro de solicitação, siga estas etapas:
      1. Em Parâmetros da solicitação, clique em Adicionar campo. A caixa de diálogo Adicionar campo aparece.
      2. No campo Chave do campo, digite where[0][attribute].
      3. No campo Valor do campo, insira contactId.
      4. Clique em Salvar.

   2. Para configurar o restante dos parâmetros de solicitação, repita a etapa anterior usando as informações na tabela a seguir. Você já criou o primeiro parâmetro de solicitação.

      Chave de campo	Valor do campo
      where[0][attribute]	contactId
      where[0][type]	equals
      where[0][value]	{ACCOUNT_ID}
      contactId	{ACCOUNT_ID}
      sortBy	createdAt
      asc	false

6. No campo Localização dos dados de resposta, insira data.list.

7. Clique em Salvar.

8. Clique em Voltar às configurações do desenvolvedor para retornar à página Configurações do desenvolvedor.

Configurar um endpoint "Encontrar um registro por ID"

Usado com frequência em interações baseadas em SDK, permite transmitir um ID de registro específico para associar à interação. Para configurar o endpoint "Encontrar um registro por ID", siga estas etapas:

1. No painel CRM, acesse a seção Registro da API.
2. Em Encontrar um endpoint de registro por ID, clique em Configurar. A página Configuração genérica do endpoint da API aparece.
3. No campo URL, insira o URL para pesquisar uma conta. Por exemplo, https://YOUR_ESPO_DOMAIN/api/v1/Case/{RECORD_ID}.
4. Em Método, selecione GET.
5. No campo Localização dos dados de resposta, insira data.
6. Clique em Salvar.
7. Clique em Voltar às configurações do desenvolvedor para retornar à página Configurações do desenvolvedor.

Configurar um endpoint "Criar um registro"

Para configurar o endpoint de criação de um registro, siga estas etapas:

1. No painel CRM, acesse a seção Registro da API.
2. Em Criar um endpoint de registro, clique em Configurar. A página Configuração genérica do endpoint da API aparece.
3. No campo URL, insira o URL para pesquisar uma conta. Por exemplo, https://YOUR_ESPO_DOMAIN/api/v1/Case.
4. Em Método, selecione POST.

5. Para configurar Parâmetros de solicitação, faça o seguinte:

   1. Para configurar o primeiro parâmetro de solicitação, siga estas etapas:
      1. Em Parâmetros da solicitação, clique em Adicionar campo. A caixa de diálogo Adicionar campo aparece.
      2. No campo Chave do campo, digite description.
      3. No campo Valor do campo, insira CALL Session:{CALL_ID}.
      4. Clique em Salvar.

   2. Para configurar o restante dos parâmetros de solicitação, repita a etapa anterior usando as informações na tabela a seguir. Você já criou o primeiro parâmetro de solicitação.

      Chave de parâmetro	Valor do parâmetro
      description	Call Session: {CALL_ID}
      name	Inbound Call from {ANI}
      contactId	{ACCOUNT_ID}
      status	New
      cchatId	{CHAT_ID}
      ccallId	{CALL_ID}
      cChannel	{CHANNEL}
      Type	{SESSION_TYPE}

6. No campo Localização dos dados de resposta, insira data.

7. No campo Localização do ID do objeto, insira id.

8. Clique em Salvar.

9. Clique em Voltar às configurações do desenvolvedor para retornar à página Configurações do desenvolvedor.

Configurar um endpoint para atualizar um registro

Para configurar o endpoint "Atualizar um registro", siga estas etapas:

1. No painel CRM, acesse a seção Registro da API.
2. Em Atualizar um endpoint de registro, clique em Configuração. A página Configuração genérica do endpoint da API aparece.
3. No campo URL, insira o URL para pesquisar uma conta. Por exemplo, https://YOUR_ESPO_DOMAIN/api/v1/Case/{RECORD_ID}.
4. Em Método, selecione PUT.

5. Para configurar Parâmetros de solicitação, faça o seguinte:

   1. Para configurar o primeiro parâmetro de solicitação, siga estas etapas:
      1. Em Parâmetros da solicitação, clique em Adicionar campo. A caixa de diálogo Adicionar campo aparece.
      2. No campo Chave do campo, digite parentId.
      3. No campo Valor do campo, insira {RECORD_ID}.
      4. Clique em Salvar.

   2. Para configurar o restante dos parâmetros de solicitação, repita a etapa anterior usando as informações na tabela a seguir. Você já criou o primeiro parâmetro de solicitação.

      Chave de parâmetro	Valor do parâmetro
      parentId	{RECORD_ID}
      parentType	Case
      status	New
      description	{TICKET_DESCRIPTION}

6. No campo Local dos dados de resposta, insira data.

7. Clique em Salvar.

8. Clique em Voltar às configurações do desenvolvedor para retornar à página Configurações do desenvolvedor.