Um terminal é uma das extremidades de um canal de comunicação. Quando uma API interage com outro sistema, os pontos de contato dessa comunicação são considerados terminais. Para APIs, um terminal pode incluir um URL de um servidor ou serviço. Cada terminal é o local a partir do qual as APIs podem acessar os recursos de que precisam para executar suas funções. For example, https://lumapro.serviceaide.com/gateway/api/v1.
Veja a seguir as várias APIs da Luma disponíveis para desenvolvedores de habilidades:
GetContact
A API GetContact da Luma é usada para verificar se o usuário existe na Luma e recuperar detalhes do usuário, como Nome de exibição, Número de telefone e ID de contato. Use os seguintes detalhes para configurar e usar a operação do serviço web para sua habilidade:
- Gere e copie o token de acesso à API da Luma VA e o transmita à API como o token "Luma-api-access-key" no cabeçalho global. Adicione a permissão Gerenciamento de usuários à API chave de acesso à API. Consulte Criar e gerenciar chaves de acesso à API para criar uma chave de acesso à API com permissão Gerenciamento de usuários.
- Obtenha a ID externa do tenant e a transmita à API como o token 'Luma-tenant-externalId' no cabeçalho global. Clique no link Tenant → Configurações. Copie a ID externa do tenant nas Informações do tenant. Consulte Informações do tenant para obter mais detalhes.
Método HTTP para a operação: GET
URI: /contatos
- Passe o nome de usuário fornecido pelo usuário final como parâmetros de consulta para o serviço web.
- Como resposta, o serviço web verifica se o usuário está disponível na Luma e recupera os detalhes do usuário. Na configuração da resposta:
Verifique se nenhum dado ou erro foi recebido.
Se o usuário for encontrado, extraia os detalhes do usuário, como número de telefone registrado para validação do usuário.
Extraia a ID de contato do usuário correspondente, que será usada para associar a ID de contato da Luma à conta do canal.
Se o usuário existir, a Luma retornará uma matriz de detalhes do usuário. Se a matriz de '' dados '' retornar qualquer valor, isso significa que um único ou vários usuários existem na Luma, que se alinham aos dados, como mostrado abaixo.
{
"status": "Success",
"statusCode": 0,
"statusLine": "Successfully retrieved the contact profile(s).",
"errors": null,
"resultData": [
{
"href": "/api/v1/contacts/2",
"id": 2,
"tenant": {
"href": "/api/v1/tenants/1597",
"tenantId": 1597,
"externalId": null,
"name": null,
"subDomain": null,
"symbol": null,
"status": null,
"description": null,
"provisioningDefaults": null,
"subscription": null
},
"subTenant": {
"href": "/api/v1/subtenants/1",
"id": 1,
"tenant": null,
"name": null,
"description": null,
"parentSubTenant": null
},
"createdDate": "2021-06-04T07:51:36.482Z",
"createdByContact": {
"href": "/api/v1/contacts/1",
"id": 1,
"tenant": null,
"subTenant": null,
"createdDate": null,
"createdByContact": null,
"modifiedDate": null,
"modifiedByContact": null,
"contactExternalId": null,
"userName": null,
"email": null,
"title": null,
"firstName": null,
"lastName": null,
"middleName": null,
"phone": null,
"timezone": null,
"language": null,
"memberships": [],
"customAttributes": [],
"lastUpdatedSourceType": "WEB_UI",
"lastUpdatedSource": "Bot Builder",
"displayName": null,
"conversationCount": 0,
"recordStatus": {
"href": null,
"id": 1,
"status": "active",
"description": null
},
"deactivationSource": null
},
"modifiedDate": "2021-06-04T07:51:36.482Z",
"modifiedByContact": {
"href": "/api/v1/contacts/1",
"id": 1,
"tenant": null,
"subTenant": null,
"createdDate": null,
"createdByContact": null,
"modifiedDate": null,
"modifiedByContact": null,
"contactExternalId": null,
"userName": null,
"email": null,
"title": null,
"firstName": null,
"lastName": null,
"middleName": null,
"phone": null,
"timezone": null,
"language": null,
"memberships": [],
"customAttributes": [],
"lastUpdatedSourceType": "WEB_UI",
"lastUpdatedSource": "Bot Builder",
"displayName": null,
"conversationCount": 0,
"recordStatus": {
"href": null,
"id": 1,
"status": "active",
"description": null
},
"deactivationSource": null
},
"contactExternalId": "8ad83517-2a3d-4075-99d0-888e6b4a5458",
"userName": "John",
"email": "test@gmail.com",
"title": null,
"firstName": "John",
"lastName": "Smith",
"middleName": null,
"phone": "+91 1235667788",
"timezone": null,
"language": {
"href": "/api/v1/languages/1",
"id": 1,
"tenant": null,
"subTenant": null,
"createdDate": null,
"createdByContact": null,
"modifiedDate": null,
"modifiedByContact": null,
"code": null,
"name": null,
"displayName": null,
"locale": null
},
"memberships": [],
"customAttributes": [],
"lastUpdatedSourceType": "WEB_UI",
"lastUpdatedSource": "Bot Builder",
"displayName": "John Smith",
"conversationCount": 0,
"recordStatus": {
"href": "/api/v1/recordStatus/1",
"id": 1,
"status": null,
"description": null
},
"deactivationSource": null
}
],
"warnings": [],
"timestamp": 1622794112816,
"reasonPhrase": null,
"metaInfo": {
"totalRecordCount": 1,
"currentRecordCount": 1
}
}
Se o usuário não existir, a Luma retornará uma matriz de ''dados'' vazia, como mostrado abaixo.
{
"status": "Success",
"statusCode": 0,
"statusLine": "Successfully retrieved the contact profile(s).",
"errors": null,
"resultData": [],
"warnings": [],
"timestamp": 1622793185448,
"reasonPhrase": null,
"metaInfo": {
"totalRecordCount": 0,
"currentRecordCount": 0
}
}
MapUserToChannelAccount
A API MapUserToChannelAccount da Luma é usada para associar o contato/usuário verificado à conta do canal com o modo e o status de autenticação apropriados.
- Gere e copie o token de acesso à API da Luma VA e o transmita à API como o token "Luma-api-access-key" no cabeçalho global. Adicione a permissão Bot à chave de acesso à API. Consulte Criar e gerenciar chaves de acesso à API para criar uma chave de acesso à API com a permissão Bot.
- Obtenha a ID externa do tenant e a transmita à API como o token 'Luma-tenant-externalId' no cabeçalho global. Clique no link Tenant → Configurações. Copie a ID externa do tenant nas Informações do tenant. Consulte Informações do tenant para obter mais detalhes.
Método HTTP para a operação: PUT
URI: /contactchannelauthentication/{channelAccountId}
- Passe a ID da conta do canal como parâmetros de caminho para o serviço web. A ID da conta do canal do usuário está disponível na variável de contexto do canal @{channel.channelAccountId}
Passe a ID da conta do canal e a ID de contato da Luma do usuário como carga de saída. A ID de contato é a ID de contato do usuário na Luma e é obtida usando a API GetContact.
{ "ccaExternalId": "@{channel.channelAccountId}", "authenticationStatus": "SUCCESS", "authenticationMode": "MANUAL", "contact": { "id": @{global.ootb_contact_id} } }- Como resposta, o serviço web mapeia a ID do usuário Luma para a ID da conta do canal e responde com o status bem-sucedido. O usuário agora está registrado na Luma para o canal de bate-papo específico
Observação
É obrigatório passar a ID de contato do usuário na Luma e a ID da conta do canal na solicitação.