Pular para o conteúdo principal

Artigo atualizado: 04 de fevereiro de 2022

API Sparkcentral CRM

A integração com o Sparkcentral CRM permite que você extraia dados de contato do cliente de CRMs ou outros aplicativos de negócios internos para o Sparkcentral. Para integrar seu CRM ao Sparkcentral, você precisa fornecer um ponto de extremidade HTTPS para pesquisas. Você também pode fornecer um ponto de extremidade HTTPS opcional para lidar com solicitações de gravação de retorno e um ponto de extremidade HTTP para o Sparkcentral enviar notificações de nosso aplicativo para o seu CRM.

Segurança e autenticação

Ao enviar ou receber dados do Sparkcentral, fornecemos duas opções de autenticação. Ambos os mecanismos estão em vigor para que você possa garantir que a solicitação seja originada do Sparkcentral.

Segredo compartilhado

Quando você escolhe o mecanismo de segredo compartilhado e configura um URL, você recebe um segredo. Com o segredo fornecido, você pode calcular a assinatura que permite verificar se a chamada foi originada do Sparkcentral. Com esse mecanismo, cada solicitação do Sparkcentral contém o cabeçalho X-Sparkcentral-Signature. Aqui está um exemplo de uma solicitação:

Copiar

curl -X POST https://sparkcentral-lookup -H 'content-type: application/json' -H 'aceitar: aplicativo/json' -H 'X-Sparkcentral-Assinatura: e6f93239a06e46ae9654fc9ad2fb4e1cc4eb213830a0d94e711570c047e43c57' -d '{"email":"fj@example.com"}'

A assinatura é gerada usando o algoritmo HMAC-SHA256 com o segredo compartilhado e o corpo da solicitação. Use seu segredo para calcular a assinatura e comparar com a assinatura fornecida. Tanto a chave secreta que você recebeu quanto a assinatura são codificadas como strings hexadecimais. Certifique-se de converter o segredo compartilhado de sua representação hexadecimal para o formato binário antes de usá-lo. A maioria dos idiomas vem com bibliotecas prontas para usar para verificar essa assinatura. Por exemplo, veja como se parece no JavaScript:

Copiar


const crypto = require ("crypto");
const SparkCentralSecret ="... "; //não compartilhe!
const expectedSignature = request.headers ["X-Sparkcentral-Signature"];
const ActualSignature = cripto
.createHmac ("sha256 ", buffer.from (SparkCentralSecret," hexadecimal"))
.update (request.body," utf-8")
.digest ("hex");
if (Assinatura real! == ExpectedSignature){
                throw new createError.Unauthorized("X-Sparkcentral-Signature wrong");
                }
console.log (JSON.parse (request.body) .email);

OAuth

Se seus endpoints suportarem OAuth2, você poderá configurar suas credenciais de cliente, um URL de token e, opcionalmente, um Escopo no Sparkcentral.

Usamos o fluxo de credenciais do cliente OAuth2 para autenticar em seu CRM. O URL do token é o ponto de extremidade onde podemos autenticar com essas credenciais e recuperar um token de acesso. Para fazer as solicitações reais de pesquisa, gravação ou notificação, usamos o token no cabeçalho de autorização para autenticar.

Pesquisa

Criar atributos de contato

  1. No Sparkcentral, acesse Configurações do administrador, expanda o espaço de trabalho do agente, selecione Atributos de contato e, em seguida, selecione Adicionar atributo.
  2. Na caixa Editar atributo, selecione Gerenciado pelo CRM. O CRM é a fonte da verdade para esses atributos. Depois de serem importados para o Sparkcentral, eles só mudam quando o valor muda no CRM.
  3. Identifique os atributos de pesquisa selecionando Usar como atributo de pesquisa. Eles são usados pelo CRM para encontrar os dados de um cliente. Por exemplo, se você quiser encontrar um cliente por endereço de e-mail, crie um atributo chamado “E-mail” e designe-o como uma pesquisa. Quando a solicitação é feita do Sparkcentral para o seu CRM, os campos de pesquisa são incluídos no corpo da solicitação.
  4. Crie um alias para o atributo. Na caixa Identificador exclusivo, insira um alias para o atributo de pesquisa. Isso é usado para mapear a resposta do seu sistema para o atributo.

Configurar URL de integração

Para extrair dados do seu CRM para o Sparkcentral, você precisa implementar um endpoint POST que aceite uma solicitação JSON e retorne uma resposta JSON. A solicitação contém os atributos de pesquisa e a resposta deve conter os dados de contato do seu CRM

Depois que esse endpoint for implementado, configure-o como o URL de pesquisa:

  1. Vá para Configurações do administrador.

  2. Expanda a integração e as APIs.

  3. Selecione CRM.

Lidar com a solicitação

Quando o endpoint em seu sistema estiver pronto e configurado no Sparkcentral e um ou mais atributos de pesquisa forem identificados, você poderá fazer uma solicitação por meio do botão Pesquisar na exibição de conversa.

Depois de fazer a pesquisa em seu sistema, transmita os atributos de volta para o Sparkcentral como uma resposta JSON. As chaves no objeto de atributos correspondem aos aliases que foram adicionados anteriormente no Sparkcentral. Se um atributo gerenciado do CRM estiver ausente do objeto ou a chave tiver um valor nulo, seu valor será excluído no Sparkcentral. A Sparkcentral espera a resposta neste formato:

Resposta 200 (application/json)

Copiar
{
"autoConfirm": false,
"atributos":{
"email": "fj@example.com",
"id": "98765432",
"first_name": "Fred",
"last_name": "Jones",
"last_order_number": null
}
}

Confirme seus atributos

Os atributos do CRM enviados de volta na resposta devem ser confirmados antes de serem salvos no Sparkcentral. Existem duas maneiras de fazer isso:

  • Selecione o botão Confirmar quando você vir os atributos do CRM exibidos no Sparkcentral após a solicitação de pesquisa.
  • Adicione um campo Confirmação automática à resposta:

Resposta 200 (application/json)

Copiar
{
"autoConfirm": true,
"atributos":{
"email": "fj@example.com",
"id": "98765432",
"first_name": "Fred",
"last_name": "Jones"
}
}

O campo AutoConfirme diz ao Sparkcentral para salvar automaticamente os atributos sem precisar usar o botão Confirmar.

Escrever de volta

Você pode ser notificado sempre que uma conversa tiver ocorrido no Sparkcentral ou um agente definir uma conversa atual como estado pendente. Isso permite que você salve detalhes da conversa em seu sistema CRM existente. Outros casos de uso incluem acionar pesquisas CSAT, criação de casos e insights de clientes expandidos a partir de perfis de mídia social.

Configurar o URL de gravação

Para enviar dados do Sparkcentral para o CRM, você precisa implementar um endpoint POST que aceite uma solicitação JSON e retorne uma resposta JSON. A solicitação contém carga útil de gravação, e o código de status da resposta representa sua capacidade de analisar a carga útil e a capacidade do CRM de ingerir os dados

Configure o ponto de extremidade como o URL de gravação de retorno:

  1. Vá para Configurações do administrador.

  2. Expanda a integração e as APIs.

  3. Selecione CRM.

Lidar com a solicitação

Quando o endpoint em seu sistema está pronto e configurado no Sparkcentral, e eventos relevantes ocorrem dentro do Sparkcentral, as solicitações são enviadas para o endpoint configurado. Todas as cargas de gravação decodificadas têm os seguintes campos:

  • type: Uma string que define que tipo de solicitação de gravação está sendo processada. Usado para sugerir a estrutura do campo de dados.
  • version: Um número que designa a versão do tipo de solicitação. Usado para marcar alterações na estrutura do campo de dados.
  • idempotencyKey: uma string que identifica exclusivamente cada evento a ser reescrito. Usado para ajudar a garantir que cada solicitação seja processada apenas uma vez.
  • data: um objeto que contém dados estruturados para o tipo específico de gravação. Por exemplo, um evento do tipo CONVERSATION_RESOLVED tem campos como meio, canal, mensagens*, notas, tópicos, ContactProfile*, atributos* e agente, entre outros.

* Aplica-se a todos os meios, exceto o Twitter. O identificador do Twitter, os tweets e as transcrições de mensagens diretas e os atributos de contato médio do Twitter (nome do Twitter, número de seguidores, etc.) não são enviados na carga útil, de acordo com as políticas de uso de dados do Twitter.

Eventos CONVERSATION_RESOLVED e CONVERSATION_SET_TO_PENDING

Eventos com um tipo de 'CONVERSATION_RESOLVED' ou 'CONVERSATION_SET_TO_PENDING' têm a seguinte estrutura de dados:

Copiar
{
"timestamp":" 2021-04-28T 09:43:26 .635984618Z",
"IDempotencykey ":" 6ebc6a78-d9e9-48be-b172-51eda40b7af8",
"versão": 1,
"tipo":" CONVERSATION_RESOLVED",
"dados": {
"conversação":{
      "id": "0ad42eef-a806-11eb-9642-f1ceb2f21def",
      "createdAt": "2021-04-28T09:42:27.004817183Z",
      "previousStatus": "new",
      "currentStatus": "resolved"
    },
"médio":{
      "id": "smooch-whatsapp"
    },
"canal":{
      "id": "0-02534c5ac04-000-261ad914",
      "name": "channelname"
    },
"agente":{
      "id": "11599",
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@Hootsuite.com"
    },
"ContactProfile":{
      "id": "693ed54b-a426-11eb-9363-cffd945b4b2f",
      "mediumContactProfileId": "bb7b0f8f00cc989b97f0725b",
      "primaryIdentifier": "John Smith",
      "secondaryIdentifier": "+32439487192",
      "pictureUrl": null
    },
"StatusUpdatedReason": "5fd023f6-2e66-11eb-be07-092841b0717d - Resposta não necessária",
"StatusUpdateedComentário": "não é uma pergunta",
"StatusUpdateDat":" 2021-04-28T 09:43:26 .532948586Z ",
"mensagens": [
{
        "id": "0ad20c0d-a806-11eb-9642-f799d0e531de",
        "direction": "INBOUND",
        "text": "Figuur"
      },
{
        "id": "10664516-a806-11eb-9642-fbd9d431bd78",
        "direction": "OUTBOUND",
        "text": "dsghkjsdgmhlknsdmglhkjmsdlgkhjmsdgkljhlmdkgjh"
      }
],
"ContactAttributes": [
{
        "attribute": "smooch-whatsapp-profile-name",
        "value": "John Smith",
        "source": "MEDIUM"
      },
{
        "attribute": "smooch-whatsapp-phone-number",
        "value": "+32471263345",
        "source": "MEDIUM"
      },
{
        "attribute": "email",
        "value": "john.smith@Hootsuite.com",
        "source": "CRM_CONFIRMED"
      },
{
        "attribute": "first_name",
        "value": "John",
        "source": "CRM_CONFIRMED"
      },
{
        "attribute": "last_name",
        "value": "Smith",
        "source": "CRM_CONFIRMED"
      },
{
        "attribute": "company",
        "value": "Hootsuite",
        "source": "CRM_CONFIRMED"
      },
{
        "attribute": "spark-language",
        "value": "nl",
        "source": "CRM_CONFIRMED"
      }
],
"notas": [],
"tópicos": []
}
}

Escrever novamente

Se a solicitação de gravação expirar ou o endpoint retornar um código de status sem sucesso (2XX), o Sparkcentral tentará novamente com recuos exponenciais. A solicitação é enviada novamente com um atraso de 1, 2, 4, 8, 16 e 32 horas após cada nova tentativa (um total de 6 solicitações), desde que a solicitação não seja bem-sucedida. Se a solicitação ainda não tiver sido bem-sucedida após 6 solicitações, armazenaremos os detalhes da solicitação com falha para referência futura. Recomendamos que você inspecione os logs do endpoint regularmente para garantir que as solicitações de gravação sejam processadas corretamente na primeira vez. Para distinguir entre eventos únicos, cada solicitação recebe uma chave de idempotência.

Chave de idempotência

As solicitações de gravação de retorno do Sparkcentral fazem uso de uma chave de idempotência, que permite que o endpoint de gravação de volta garanta que ele processe cada solicitação uma vez. Essa chave ajuda quando as solicitações são enviadas várias vezes durante a programação de novas tentativas, para que o endpoint possa lidar com solicitações de forma idempotente. A chave é exclusiva por solicitação.

Notificação

Configurar o URL de notificação

Quando você envia seus atributos de contato gerenciados do CRM, o Sparkcentral faz alguma validação na resposta. Para ver erros de validação, fornecemos uma maneira de enviar notificações do Sparkcentral para o seu sistema. Você precisa fornecer um endpoint POST que aceite um corpo de solicitação JSON. Configure um URL de notificação na mesma tela em que você configurou um URL de pesquisa:

  1. Vá para Configurações do administrador.

  2. Expanda a integração e as APIs.

  3. Selecione CRM.

Lidar com a solicitação

Quando ocorrem erros de validação, o Sparkcentral envia uma solicitação para o URL de notificação configurado. Uma solicitação se parece com isso:

Copiar
{
"timestamp": "2019-01-30T15:49:10.630397Z",
"version": 1,
"eventType": "DATA_IMPORT_ERROR",
"messages": [
"testMessage1 key:testKey1 value:testValue1",
"testMessage2 key:testKey2 value:testValue2"
]
}

A solicitação contém esses dois campos:

  • EventType
  • messages — uma matriz de mensagens de erro explícitas

A seguir estão os tipos de evento que podem ser enviados pelo Sparkcentral.

tipos de eventos
Tipo de evento Descrição
DATA_IMPORT_ERROR Ocorreu um erro ao extrair dados do CRM para o Sparkcentral.

A resposta a essa solicitação pode ser 204. O Sparkcentral não espera nada no corpo da resposta.

Outras ações

Atualizar

O botão Atualizar na Exibição de Conversa rebusca os atributos gerenciados do CRM. Como esses atributos foram confirmados anteriormente, a etapa de confirmação não é necessária.

Desvincular

O botão Desvincular na Exibição de conversa remove os atributos gerenciados do CRM do Sparkcentral.

Confirmar

O botão Confirmar armazena as informações validadas associadas do CRM para o banco de dados do Sparkcentral.

Claro

O botão Limpar redefine os dados que foram puxados pelo endpoint de pesquisa.

 

Não consegue encontrar o que está procurando? Estamos aqui para ajudar