Endpoints de API da plataforma de chat

Os endpoints da API da plataforma de chat oferecem acesso aos objetos de chat. Um objeto de chat é criado para cada conversa feita com e pela Contact Center AI Platform (CCAI Platform).

Confira abaixo os endpoints da API da plataforma de chat:

Objeto de chat

Um objeto de chat é criado para cada sessão de chat na Web e em dispositivos móveis na plataforma CCAI. Confira o objeto de chat:

{
    "id": "integer",
    "status": "string",
    "status_text": "string",
    "features": [
        "string",
        "string"
    ],
    "created_at": "string",
    "ends_at": "string",
    "timeout_at": "string",
    "agent": {
        "id": "integer",
        "name": "string",
        "first_name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "virtual_agent": {
        "id": "integer",
        "name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "all_agents": [
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "all_virtual_agents": [
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "lang": "string",
    "menus": [
        {
            "id": "integer",
            "name": "string"
        },
        {
            "id": "integer",
            "name": "string"
        }
    ],
    "end_user": {
        "id": "integer",
        "identifier": "string"
    }
}

Atualizar uma conversa

Parâmetro Obrigatório Tipo de dados Definição
ID TRUE Número inteiro O ID do chat a ser atualizado

Endpoint:

Method: PATCH
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:id

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json
Aceitar application/json

Corpo:

{
    "finished_by_user_id": "integer",
    "chat": {
        "deflection_channel": "string",
        "status": "string",
        "escalation_id": "integer"
    }
}

Exemplo de solicitação e respostas

As seções a seguir fornecem exemplos de solicitações ao endpoint.

Atualizar uma conversa

Este exemplo demonstra a atualização bem-sucedida de um chat atual

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json
Aceitar application/json

Consulta

Chave Valor Descrição
ID Número inteiro (Obrigatório)

Corpo:

{
    "finished_by_user_id": "integer",
    "chat": {
        "deflection_channel": "string",
        "status": "finished",
        "escalation_id": "integer"
    }
}
Resposta
{
    "id": "integer",
    "status": "string",
    "status_text": "string",
    "features": [
        "string",
        "string"
    ],
    "created_at": "string",
    "ends_at": "string",
    "timeout_at": "string",
    "agent": {
        "id": "integer",
        "name": "string",
        "first_name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "virtual_agent": {
        "id": "integer",
        "name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "all_agents": [
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "all_virtual_agents": [
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "lang": "string",
    "menus": [
        {
            "id": "integer",
            "name": "string"
        },
        {
            "id": "integer",
            "name": "string"
        }
    ],
    "end_user": {
        "id": "integer",
        "identifier": "string"
    }
}

Código de status:200

Enviar uma mensagem em um chat

Esse método permite enviar uma mensagem em uma sessão de chat aberta.

Parâmetro Obrigatório Tipo de dados Definição
ID TRUE Número inteiro O ID do chat em que a mensagem deve ser enviada.

Endpoint:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:id/message

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json

Corpo:

{
    "from_user_id": integer,
    "message": {
            "type": "string",
            "content": "string"
            }
    }
}

Exemplo de solicitação e respostas

As seções a seguir fornecem exemplos de solicitações ao endpoint.

Envio de mensagem bem-sucedido

Este exemplo demonstra o envio bem-sucedido de uma mensagem para uma sessão de chat em andamento.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json
Aceitar application/json

Consulta

Chave Valor Descrição
ID Número inteiro (Obrigatório)

Corpo:

{
    "from_user_id": integer,
    "message": {
            "type": "string",
            "content": : "string"
            }
    }
}
Resposta
{
}

Código de status:200

Encaminhar conversa com agente virtual

Escalonar um chat de um agente virtual para um agente humano.

Parâmetro Obrigatório Tipo de dados Definição
chat_id TRUE Número inteiro O ID de chat necessário para encaminhar.

Endpoint:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/escalations

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json
Aceitar application/json

Corpo:

{
    "reason": "string",
    "force_escalate": "boolean"
}

Exemplo de solicitação e respostas

As seções a seguir fornecem exemplos de solicitações ao endpoint.

Transferência de chat concluída

Este exemplo demonstra a solicitação para encaminhar um chat atual para um agente humano.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json
Aceitar application/json

Consulta

Chave Valor Descrição
chat_id Número inteiro (Obrigatório)

Corpo:

{
    "reason": "by_end_user_ask",
    "force_escalate": true
}
Resposta
{
    "id": "integer",
    "chat_id": "integer",
    "status": "string"
}

Código de status:200

Atualizar encaminhamento

Usado apenas para selecionar o canal de evasão.

Parâmetro Obrigatório Tipo de dados Definição
chat_id TRUE Número inteiro O ID de chat necessário para atualizar o ID do menu de redirecionamento.
ID TRUE Número inteiro O ID do menu obrigatório.

Endpoint:

Method: PATCH
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/escalations/:id

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json

Corpo:

{
    "deflection_channel": "string"
}

Exemplo de solicitação e respostas

As seções a seguir fornecem exemplos de solicitações ao endpoint.

Atualização de encaminhamento concluída

Este exemplo demonstra uma atualização bem-sucedida do canal de encaminhamento.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json
Aceitar application/json

Consulta

Chave Valor Descrição
chat_id Número inteiro (Obrigatório)
ID Número inteiro (Obrigatório)

Corpo:

{
    "deflection_channel": "string"
}
Resposta
{
    "id": "integer",
    "chat_id": "integer",
    "status": "string"
}

Código de status:200

Adicionar a foto enviada ao chat

Adicionar a um chat uma foto que foi enviada por upload para o armazenamento de mídia

Parâmetro Obrigatório Tipo de dados Definição
chat_id TRUE Número inteiro O ID de chat necessário para adicionar a foto.

Endpoint:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}/apps/api/v1/chats/:chat_id/photos

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json
Aceitar application/json

Corpo:

{
    "photo": [
        {
            "s3_path": "string",
            "photo_type": "string"
        },
        {
            "s3_path": "string",
            "photo_type": "string"
        }
    ]
}

Exemplo de solicitação e respostas

As seções a seguir fornecem exemplos de solicitações ao endpoint.

Adição de uma foto ao chat

O exemplo a seguir demonstra a adição de uma foto que foi enviada para um armazenamento de mídia a uma conversa de chat.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json
Aceitar application/json

Consulta

Chave Valor Descrição
chat_id Número inteiro (Obrigatório)

Corpo:

{
    "photo": [
        {
            "s3_path": "string",
            "photo_type": "string"
        },
        {
            "s3_path": "string",
            "photo_type": "string"
        }
    ]
}
Resposta
{
    "url": "string",
    "media_id": "integer"
}

Código de status:200

Buscar todas as fotos do chat

Recebe o ID da mídia e o URL de armazenamento de todas as fotos anexadas à conversa.

Parâmetro Obrigatório Tipo de dados Definição
chat_id TRUE Número inteiro O ID do chat necessário para receber as informações de mídia.

Endpoint:

Method: GET
Type:
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/photos

Cabeçalhos:

Chave Valor Descrição
Aceitar application/json

Exemplo de solicitação e respostas

As seções a seguir fornecem exemplos de solicitações ao endpoint.

Recuperação bem-sucedida das informações da foto de um chat

Este exemplo demonstra uma chamada bem-sucedida para a API para receber as informações da foto de uma sessão de chat atual.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Aceitar application/json

Consulta

Chave Valor Descrição
chat_id Número inteiro (Obrigatório)
Resposta
[
    {
        "url": "string",
        "media_id": "integer"
    },
    {
        "url": "string",
        "media_id": "integer"
    }
]

Código de status:200

Receber um URL de upload de fotos pré-assinadas

Usado para receber um URL de upload pré-assinado para fotos.

Parâmetro Obrigatório Tipo de dados Definição
chat_id TRUE Número inteiro O ID de chat obrigatório que será associado ao URL da foto pré-assinada.

Endpoint:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/photos/upload

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json
Aceitar application/json

Exemplo de solicitação e respostas

As seções a seguir fornecem exemplos de solicitações ao endpoint.

Recuperação bem-sucedida do URL assinado para upload

Confira abaixo um exemplo de solicitação bem-sucedida com recuperação de um URL assinado para upload de fotos.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Aceitar application/json

Consulta

Chave Valor Descrição
chat_id Número inteiro (Obrigatório)
Resposta
{
    "url": "string",
    "fields": {
        "key": "string",
        "success_action_status": "string",
        "Content-Type": "string",
        "Cache-Control": "string",
        "acl": "string",
        "policy": "string",
        "x-amz-credential": "string",
        "x-amz-algorithm": "string",
        "x-amz-date": "string",
        "x-amz-security-token": "string",
        "x-amz-signature": "string",
        "x-goog-algorithm": "string",
        "x-goog-credential": "string",
        "x-goog-date": "string",
        "x-goog-signature": "string"
    }
}

Código de status:200

Adicionar o vídeo enviado à conversa

Adicione a uma conversa um vídeo que foi enviado para o armazenamento de mídia.

Parâmetro Obrigatório Tipo de dados Definição
chat_id TRUE Número inteiro O ID de chat obrigatório a que o vídeo deve ser associado.

Endpoint:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/videos

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json
Aceitar application/json

Corpo:

{
    "video": {
        "s3_path": "string",
        "gcs_path": "string"
    }
}

Exemplo de solicitação e respostas

As seções a seguir fornecem exemplos de solicitações ao endpoint.

Upload de um vídeo para uma sessão de chat

Este exemplo demonstra o upload bem-sucedido de um vídeo para uma sessão de chat.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Aceitar application/json

Consulta

Chave Valor Descrição
chat_id Número inteiro (Obrigatório)

Corpo:

{
    "photo": [
        {
            "s3_path": "string",
            "photo_type": "string"
        },
        {
            "s3_path": "string",
            "photo_type": "string"
        }
    ]
}
Resposta
Body
{
    "url": "string",
    "media_id": "integer"
}

Código de status:200

Buscar todos os vídeos do chat

Recebe o ID da mídia e o URL de armazenamento de todos os vídeos anexados à conversa.

Parâmetro Obrigatório Tipo de dados Definição
chat_id TRUE Número inteiro O ID da conversa obrigatório para recuperar os URLs de vídeo.

Endpoint:

Method: GET
Type:
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/videos

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json
Aceitar application/json

Exemplo de solicitação e respostas

As seções a seguir fornecem exemplos de solicitações ao endpoint.

Recuperar todos os URLs de vídeo de uma conversa

Este exemplo demonstra a recuperação de todos os URLs de vídeo de um chat atual.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Aceitar application/json

Consulta

Chave Valor Descrição
chat_id Número inteiro (Obrigatório)
Resposta
[
    {
        "url": "string",
        "media_id": "integer"
    },
    {
        "url": "string",
        "media_id": "integer"
    }
]

Código de status:200

Receber o URL pré-assinado de upload de vídeo

Usado para receber um URL de upload pré-assinado para vídeos.

Parâmetro Obrigatório Tipo de dados Definição
chat_id TRUE Número inteiro O ID de chat obrigatório que será associado ao URL de vídeo pré-assinado.

Endpoint:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/videos/upload

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json
Aceitar application/json

Exemplo de solicitação e respostas

As seções a seguir fornecem exemplos de solicitações ao endpoint.

Recuperação bem-sucedida do URL assinado para upload de vídeo

Confira a seguir um exemplo de solicitação bem-sucedida com recuperação de um URL assinado para upload de vídeo.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Aceitar application/json

Consulta

Chave Valor Descrição
chat_id Número inteiro (Obrigatório)
Resposta
{
    "url": "string",
    "fields": {
        "key": "string",
        "success_action_status": "string",
        "Content-Type": "string",
        "Cache-Control": "string",
        "acl": "string",
        "policy": "string",
        "x-amz-credential": "string",
        "x-amz-algorithm": "string",
        "x-amz-date": "string",
        "x-amz-security-token": "string",
        "x-amz-signature": "string",
        "x-goog-algorithm": "string",
        "x-goog-credential": "string",
        "x-goog-date": "string",
        "x-goog-signature": "string"
    }
}

Código de status:200

Criar chat

Inicie uma nova sessão de chat.

Exemplo de solicitação

Método: POST

URL: https://{subdomain}.{domain}/apps/api/v1/chats

Cabeçalhos

Chave Valor Descrição
Content-Type application/json
Aceitar application/json

Corpo

{
    "chat": {
        "menu_id": "integer",
        "end_user_id": "integer",
        "lang": "string",
        "email": "string",
        "context": "object",
        "transcript": "object"
    },
    "end_user": {
        "phone": "string"
    }
}

Contexto:

O objeto context inclui o objeto value, que transmite metadados para a conversa por chat. É possível transmitir o objeto context para agentes virtuais como um parâmetro de dados não assinado. Veja o exemplo a seguir:

{
    "context": {
        {"value":
            {"foo": "bar",
             "key": "value"}
        }
    }
}

Neste exemplo, o valor do parâmetro de dados não assinados para o campo de entrada é context, e o campo de destino pode ser definido como context. Isso permite usar $session.params.context.foo ou $session.params.context.key.

Exemplo de resposta

{
    "id": "integer",
    "status": "string",
    "status_text": "string",
    "features": [
        "string",
        "string"
    ],
    "created_at": "string",
    "ends_at": "string",
    "timeout_at": "string",
    "agent": {
        "id": "integer",
        "name": "string",
        "first_name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "virtual_agent": {
        "id": "integer",
        "name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "all_agents": [
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "all_virtual_agents": [
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "lang": "string",
    "menus": [
        {
            "id": "integer",
            "name": "string"
        },
        {
            "id": "integer",
            "name": "string"
        }
    ],
    "end_user": {
        "id": "integer",
        "identifier": "string"
    }
}

Retorna um chat por ID

Esse método retorna o objeto de chat para um determinado ID de chat.

Endpoint:

Method: GET
Type:
URL: https://{subdomain}.​{domain}/apps/api/v1/chats/:id

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json
Aceitar application/json

Consulta

Chave Valor Descrição
chat_id Número inteiro (Obrigatório)

Exemplo de solicitação e respostas

As seções a seguir fornecem exemplos de solicitações ao endpoint.

Recuperar um chat

O exemplo a seguir demonstra a solicitação bem-sucedida de um ID de chat existente.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-type application/json
Aceitar application/json

Consulta

Chave Valor Descrição
chat_id Número inteiro (Obrigatório)
Resposta
{
    "id": "integer",
    "status": "string",
    "status_text": "string",
    "features": [
        "string",
        "string"
    ],
    "created_at": "string",
    "ends_at": "string",
    "timeout_at": "string",
    "agent": {
        "id": "integer",
        "name": "string",
        "first_name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "virtual_agent": {
        "id": "integer",
        "name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "all_agents": [
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "all_virtual_agents": [
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "lang": "string",
    "menus": [
        {
            "id": "integer",
            "name": "string"
        },
        {
            "id": "integer",
            "name": "string"
        }
    ],
    "end_user": {
        "id": "integer",
        "identifier": "string"
    }
}

Código de status:200

Receber atributos de dados reservados durante um chat

Endpoint

Method: GET
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:id/customer_flag

Exemplo de solicitação e respostas

Esta seção contém um exemplo de solicitação e resposta para o endpoint.

Sucesso

Este exemplo mostra uma chamada bem-sucedida.

Solicitação

Cabeçalhos

Chave Valor Descrição
Aceitar application/json

Variáveis de URL

Chave Valor Descrição
ID integer (Obrigatório)
Resposta
{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customer": "boolean"
}

Código de status 0

Atualizar atributos de dados reservados durante uma conversa

Endpoint

Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:id/customer_flag

Variáveis de URL

Chave Valor Descrição
ID integer (Obrigatório)

Body

{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customers": "boolean"
}

Enviar dados personalizados no chat

Envie dados personalizados em um chat.

Exemplo de solicitação

Método: POST

URL: https//{subdomain}.{domain}/apps/api/v1/chats/:id/custom_data

Cabeçalhos

Chave Valor Descrição
Content-Type application/json

Variáveis de URL

Chave Valor Descrição
ID (Obrigatório)

Exemplo de resposta

// Use unsecured parameter
{
"signed": false,
"data": {
// Start customer_flag fields
"reserved_verified_customer": {
"label": "LABEL 1",
"value": true
},
"reserved_bad_actor": {
"label": "LABEL 2",
"value": false
},
"reserved_repeat_customer": {
"label": "LABEL 3",
"value": true
},
// End customer_flag fields
"field1": {
"label": "LABEL 4",
"value": "dummy1"
},
"field2": {
"label": "LABEL 5",
"value": "dummy2"
}
}
}
// Use secured parameter
// {
// "signed": true,
// "signed_data": "eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21fZGF0YSI6eyJyZXNlcnZlZF92ZXJpZmllZF9jdXN0b21lciI6eyJ2YWx1ZSI6ZmFsc2V9LCJyZXNlcnZlZF9iYWRfYWN0b3IiOnsidmFsdWUiOnRydWV9LCJyZXNlcnZlZF9yZXBlYXRfY3VzdG9tZXIiOnsidmFsdWUiOmZhbHNlfSwiZmllbGQxIjp7InZhbHVlIjoiZHVtbXkxMTEifSwiZmllbGQyIjp7InZhbHVlIjoiZHVtbXkyMjIifX0sImV4cCI6MTcyOTY4MzU5MywiaWF0IjoxNzI5Njc5OTkzfQ.BMskgKTM3DbgrMLWjI46ZJ1K73H25JRd16SgHK0A1Ts"
// }
// ======================= How to create <signed_data> =======================
// payload = {
// "custom_data": {
// // Start customer_flag fields
// "reserved_verified_customer": {
// "label": "LABEL 1",
// "value": true
// },
// "reserved_bad_actor": {
// "label": "LABEL 2",
// "value": false
// },
// "reserved_repeat_customer": {
// "label": "LABEL 3",
// "value": true
// },
// // End customer_flag fields
// "field1": {
// "label": "LABEL 4",
// "value": "dummy1"
// },
// "field2": {
// "label": "LABEL 5",
// "value": "dummy2"
// }
// },
// "exp": 1734567890, // expiration timestamp
// "iat": 1734560000 // issue timestamp
// }
// signed_data = JWT.encode(payload, 'Company secret', 'HS256')
// ======================= End how to create <signed_data> =======================

Atualizar o usuário final durante uma sessão de chat em andamento

Atualiza o usuário final associado à sessão de chat ativa atual. Além disso, ele também atualiza os dados de contato vinculados ao tíquete do CRM. _Identifier é obrigatório, enquanto name, email e phone são opcionais.

Exemplo de solicitação

Método: POST

URL: https//{subdomain}.{domain}/apps/api/v1/chats/:chat_id/end-user

Cabeçalhos

Chave Valor Descrição
Content-Type application/json

Variáveis de URL

Chave Valor Descrição
chat_id

Corpo

{
    "identifier": "string",
    "name": "string",
    "email": "string",
    "phone": "string"
}

Exemplo de resposta

{
    "message": "accepted"
}