Chamar endpoints

Os endpoints da API Call fornecem acesso aos objetos de chamada. Um objeto de chamada é criado para cada chamada feita para e da Contact Center AI Platform (CCAI Platform).

Estes são os endpoints da API Call:

Objeto de chamada

Confira um exemplo do objeto de chamada:

[
  {
    "id": 0,
    "parent_id": 0,
    "lang": "en",
    "call_type": "Voice Scheduled (API)",
    "status": "scheduled",
    "created_at": "2018-06-07T19:49:52.896Z",
    "queued_at": "2018-06-07T19:49:52.896Z",
    "assigned_at": "2018-06-07T19:49:52.896Z",
    "connected_at": "2018-06-07T19:49:52.896Z",
    "ends_at": "2018-06-07T19:49:52.896Z",
    "scheduled_at": "2018-06-07T19:49:52.896Z",
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": 0,
    "has_feedback": true,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": "string",
    "out_ticket_url": "string",
    "verified": true,
    "recording_url": "string",
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_details": "string",
    "fail_reason": "nothing",
    "support_number": "string",
    "selected_menu": {
      "id": 0,
      "name": "string",
      "parent_id": 0,
      "position": 0,
      "deleted": true,
      "hidden": "string",
      "menu_type": "ivr_menu",
      "output_msg": "string"
    },
    "menu_path": {
      "items_count": 0,
      "name": "string",
      "materialized_path": "string"
    },
    "agent_info": {
      "id": 0,
      "name": "string",
      "last_name": "string",
      "first_name": "string",
      "agent_number": "string",
      "avatar_url": "string"
    },
    "end_user": {
      "id": 0,
      "identifier": "string",
      "out_contact_id": "string"
    },
    "photos": [
      {
        "id": 0,
        "photo_type": "photo",
        "url": "string"
      }
    ],
    "videos": [
      {
        "id": 0,
        "url": "string"
      }
    ],
    "transfers": [
      {
        "id": 0,
        "status": "transferring",
        "fail_reason": "nothing",
        "created_at": "2018-06-07T19:49:52.896Z",
        "from_menu": {
          "items_count": 0,
          "name": "string",
          "materialized_path": "string"
        },
        "to_menu": {
          "items_count": 0,
          "name": "string",
          "materialized_path": "string"
        },
        "from_agent": {
          "id": 0,
          "name": "string",
          "last_name": "string",
          "first_name": "string",
          "agent_number": "string",
          "avatar_url": "string"
        },
        "to_agent": {
          "id": 0,
          "name": "string",
          "last_name": "string",
          "first_name": "string",
          "agent_number": "string",
          "avatar_url": "string"
        }
      }
    ],
    "participants": [
      {
        "id": 0,
        "type": "end_user",
        "status": "waiting",
        "call_id": 0,
        "user_id": 0,
        "end_user_id": 0,
        "call_duration": 0,
        "hold_duration": 0,
        "connected_at": "2018-06-07T19:49:52.896Z",
        "ended_at": "2018-06-07T19:49:52.896Z",
        "fail_reason": "nothing"
      }
    ]
  }
]

Definições de status das chamadas

O campo de status pode estar em qualquer um dos seguintes estados:

Status da chamada Descrição
Selecionando Estado que ocorre quando um usuário final liga para a central de atendimento, mas ainda está navegando pelas opções do menu antes de ser colocado em um menu folha.
Na fila Estado que ocorre depois que o usuário final seleciona um nó de menu folha e inicia uma solicitação de chamada para ser transmitida ou multicast para um agente.
Atribuído Estado que ocorre quando um agente é selecionado para receber a ligação do usuário final. Isso acontece quando um agente atende uma ligação.
Conectando Estado que ocorre depois que um agente é atribuído e uma conexão está sendo estabelecida entre o usuário final e o agente.
Conectado Estado que ocorre quando a chamada estabeleceu uma conexão e o agente e o usuário final estão em uma ligação.
Concluído Estado que ocorre quando uma chamada termina depois de ser conectada.
Falha Estado que ocorre quando uma chamada termina antes de ser conectada. Um motivo de falha também será fornecido para mais detalhes.
Alternando Estado que ocorre quando uma chamada falha ao tentar se conectar e a plataforma CCAI tenta conectar a chamada com um provedor de VoIP diferente.
Recuperado Estado que ocorre quando uma chamada com falha é retornada. Essa nova chamada é filha da original. Recuperado e indica que o retorno de chamada foi concluído sem erros.
Programado Estado que ocorre quando um usuário final agenda uma ligação futura usando o recurso no site ou no app.
Apenas ação Estado que ocorre quando uma chamada processada pelo provedor de telefonia do cliente é conectada ao nosso SDK para iOS ou Android.
Ação concluída Estado que ocorre quando uma chamada processada pelo provedor de telefonia do cliente é conectada ao nosso SDK para iOS ou Android e termina.
Desviada Estado que ocorre com base na configuração de filas de excesso de capacidade ou ligações fora do horário comercial. As opções de rejeição incluem correio de voz, agendamento de ligação e outras. A redução varia de acordo com o canal (no app, URA, na Web).
Correio de voz Estado que ocorre quando um usuário final é redirecionado para uma opção de correio de voz e escolhe deixar uma mensagem para ouvir depois. Esse estado está presente quando o usuário final está saindo da caixa de correio de voz.
Correio de voz recebido Estado que ocorre depois que um usuário final deixa um correio de voz e um agente não ouve a mensagem.
Correio de voz lido Estado que ocorre quando um agente abre o correio de voz para ouvir.

Definições de tipo de chamada

O campo call_type só pode ter um dos seguintes valores:

Tipo de chamada Descrição
Voice Outbound (API) Chamada feita pela API Outbound Call.
Entrada de voz (API) Chamada feita pela API Incoming Call.
Voice Scheduled (API) Chamada feita pela API Scheduled Call.

Códigos de resposta comuns da API

Confira a seguir as respostas de API mais comuns:

Código de resposta Significado
201 A solicitação de API foi concluída e vai criar uma chamada.
202 A solicitação de API foi bem-sucedida, mas é necessária intervenção manual no widget para concluir a ação.
400 tipo de chamada inválido. Verifique se call_type é compatível.
400 O agente não está disponível para atender esta ligação
400 Parâmetro ausente: verifique se os parâmetros obrigatórios foram adicionados
404 Recurso não encontrado. Verifique seu subdomínio.

Chamada de saída: end_user_number

Parâmetro Obrigatório Tipo de dados Definição
call_tye TRUE String Chame "tye" para criar. "Voice Outbound (API)" e "OutboundCall" (descontinuado) estão disponíveis por enquanto
agent_email TRUE String Endereço de e-mail do agente que será atribuído à chamada de saída.
ticket_id FALSO String ID do tíquete do CRM e vai ligar para o usuário final vinculado ao tíquete.
end_user_number FALSO String Número de telefone do usuário final que vai ligar. "ticket_id" tem uma prioridade maior que "end_user_number".
outbound_number FALSO String Número de saída bem formado, gerenciado em Configurações > Números de telefone > Gerenciamento de números de telefone. O número de saída padrão será usado quando estiver vazio.
lang FALSO String Idioma da chamada. Usa códigos ISO 639-1. Padrão: "en"

Endpoint:

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

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "end_user_number": "123123",
    "lang": "en"
}

Exemplo de solicitação e respostas

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

Erro : o agente não está disponível para atender esta ligação

Este exemplo demonstra o cenário de falha quando o agente não está disponível para receber a ligação.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Resposta: Error : Agent is not available to take this call
{
    "message": "Agent is not available to take this call"
}

Código de status:400

Criar uma chamada externa com o número do usuário final

Este exemplo demonstra como fazer uma chamada externa para um número de usuário final específico.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
Resposta: crie uma chamada externa com end_user_number
{
    "id": 397,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:27:30.406Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:27:30.441Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/avatar.jpg"
    },
    "end_user": null,
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 610,
            "type": "agent",
            "status": "waiting",
            "call_id": 397,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 611,
            "type": "end_user",
            "status": "waiting",
            "call_id": 397,
            "user_id": null,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

Código de status: 201

Criar uma chamada com ID do tíquete

Este exemplo demonstra a criação de uma chamada externa com um ID de ticket específico.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "ticket_id": "71450",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
Resposta: crie uma chamada com ticket_id
{
    "id": 398,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:28:47.955Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:28:47.971Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": "71450",
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/avatar.png"
    },
    "end_user": {
        "id": 67,
        "identifier": null,
        "out_contact_id": "381630957514"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 612,
            "type": "agent",
            "status": "waiting",
            "call_id": 398,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 613,
            "type": "end_user",
            "status": "waiting",
            "call_id": 398,
            "user_id": null,
            "end_user_id": 67,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

Código de status: 201

Erro : é necessário inserir o ID do tíquete ou o número do usuário final

Este exemplo demonstra o caso de falha em que o ID do tíquete ou o número do usuário final são obrigatórios, mas não foram fornecidos.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

Resposta: Error : ticket_id or end_user_number required

{
    "message": "ticket_id or end_user_number required"
}

Código de status:400

Erro : o e-mail do agente não é válido

Este exemplo demonstra a falha quando o endereço de e-mail fornecido para um agente não é válido.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

Resposta: Erro : o e-mail do agente não é válido

{
    "message": "Not a valid agent email"
}

Código de status:400

Erro : o e-mail do agente é obrigatório

Este exemplo demonstra a falha quando um endereço de e-mail não é fornecido para o agente.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

Resposta: Error : Agent email required

{
    "message": "Agent email required"
}

Código de status:400

Erro : o agente não tem acesso para fazer ligações

Este exemplo demonstra a falha quando o agente especificado não tem permissão para fazer chamadas.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Resposta: Erro : o agente não tem acesso para fazer chamadas
{
    "message": "Agent does not have access to make calls"
}

Código de status:400

Erro : end_user_number não está bem formatado

Este exemplo demonstra o cenário de falha em que o número do usuário final fornecido não está formatado corretamente.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
Resposta: Error : end_user_number is not well-formed
{
    "message": "end_user_number is not well-formed"
}

Código de status:400

Erro : contato não encontrado

Este exemplo demonstra o cenário de falha em que o contato fornecido não existe.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "ticket_id": 1,
    "lang": "en"
}
Resposta: erro : contato não encontrado
{
    "message": "Contact not found"
}

Código de status:400

Aceita : é necessário escolher um número de saída

Neste exemplo, a chamada é aceita, mas o agente precisa escolher o número de saída a ser usado antes de fazer a ligação.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "end_user_number": "123123",
    "lang": "en"
}
Resposta
{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

Código de status:200

Erro : tipo de chamada inválido

Este exemplo demonstra o cenário de falha em que o tipo de chamada fornecido é inválido.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
Resposta: Error : Invalid call type
{
    "message": "Invalid call type"
}

Código de status:400

Solicitar o adaptador de chamadas por vários números de saída

Nesse cenário, o adaptador de chamadas recebe vários números de saída.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "end_user_number": "123123",
    "lang": "en"
}
Resposta
{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "lang": "en"
}

Código de status:200

Aceita : o agente precisa fazer uma ligação com o ID do tíquete

Este exemplo demonstra uma solicitação em que o agente precisa fazer uma ligação externa com base no ID do tíquete fornecido.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

Código de status:202

Chamada de saída - ticket_id

Parâmetro Obrigatório Tipo de dados Definição
call_type TRUE String Tipo de chamada a ser criada. "Voice Outbound (API)" e "OutboundCall" (descontinuado) estão disponíveis por enquanto
agent_email TRUE String Endereço de e-mail do agente que será atribuído à chamada de saída.
ticket_id FALSO String ID do tíquete do CRM e vai ligar para o usuário final vinculado ao tíquete.
end_user_number FALSO String Número de telefone do usuário final que vai ligar. "ticket_id" tem uma prioridade maior que "end_user_number".
outbound_number FALSO String Número de saída bem formado, gerenciado em Configurações > Números de telefone > Gerenciamento de números de telefone. O número de saída padrão será usado quando estiver vazio.
lang FALSO String Idioma da chamada. Usa códigos ISO 639-1. Padrão: "en"

Endpoint:

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

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "ticket_id": "123123",
    "lang": "en"
}

Exemplo de solicitação e respostas

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

Erro : é necessário inserir o ID do tíquete ou o número do usuário final

Neste exemplo, o cenário de falha do ID do tíquete ou do número do usuário final está ausente, mas é obrigatório.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

Resposta: Error : ticket_id or end_user_number required

{
    "message": "ticket_id or end_user_number required"
}

Código de status:400

Erro : o e-mail do agente é obrigatório

Neste exemplo, mostramos o cenário de falha em que o e-mail do agente não é fornecido, mas é obrigatório.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Resposta: Error : Agent email required
{
    "message": "Agent email required"
}

Código de status:400

Criar uma chamada externa com o número do usuário final

Neste exemplo, mostramos como criar uma chamada externa fornecendo o número do usuário final.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
Resposta: crie uma chamada externa com end_user_number
{
    "id": 397,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:27:30.406Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:27:30.441Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reaso": "not_voicemail",
    "deflection": "n_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/default-profile.png"
    },
    "end_user": null,
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 610,
            "type": "agent",
            "status": "waiting",
            "call_id": 397,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 611,
            "type": "end_user",
            "status": "waiting",
            "call_id": 397,
            "user_id": null,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

Código de status: 201

Erro : tipo de chamada inválido

Neste exemplo, mostramos o cenário de falha em que o tipo de chamada fornecido é inválido.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "ScheduledCall",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
Resposta: Error : Invalid call type
{
    "message": "Invalid call type"
}

Código de status:400

Solicitar o adaptador de chamadas por vários números de saída

Neste exemplo, mostramos como solicitar ao adaptador de chamadas vários números de telefone de saída.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "lang": "en"
}

Código de status:202

Aceita : o agente precisa fazer uma ligação com o ID do tíquete

Neste exemplo, mostramos como fazer uma chamada externa com um ID de tíquete e o agente aceita a solicitação.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-Type application/json
***Corpo:*** ```json { "call_type": "Voice Outbound (API)", "agent_email": "allen@somedomain.com", "end_user_number": "+1 205-123-4567", "lang": "en" } ``` ***Código de status:*** 202 #### Erro : o agente não tem acesso para fazer ligações Neste exemplo, mostramos o cenário de falha em que uma solicitação de criação de chamada é enviada, mas o agente não tem acesso para fazer ligações externas. ##### Solicitação ***Cabeçalhos:***
Chave Valor Descrição
Content-Type application/json

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Resposta: Erro : o agente não tem acesso para fazer chamadas
{
    "message": "Agent does not have access to make calls"
}

Código de status:400

Crie uma chamada com o ID do tíquete.

Neste exemplo, mostramos o cenário de criação de uma chamada externa com um ID de tíquete.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "ticket_id": "71450",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
Resposta: crie uma chamada com ticket_id
{
    "id": 398,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:28:47.955Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:28:47.971Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": "71450",
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/default-profile.png"
    },
    "end_user": {
        "id": 67,
        "identifier": null,
        "out_contact_id": "381630957514"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 612,
            "type": "agent",
            "status": "waiting",
            "call_id": 398,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 613,
            "type": "end_user",
            "status": "waiting",
            "call_id": 398,
            "user_id": null,
            "end_user_id": 67,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

Código de status: 201

Aceita : é necessário escolher um número de saída

Neste exemplo, mostramos o cenário em que uma solicitação de chamada é criada com a necessidade de escolher um número de saída e, em seguida, é aceita.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

Código de status:202

Erro : o agente não está disponível para atender esta ligação

Neste exemplo, mostramos o cenário de falha em que uma chamada é criada, mas o agente não está disponível para atender.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Resposta: Error : Agent is not available to take this call
{
    "message": "Agent is not available to take this call"
}

Código de status:400

Erro : o número do usuário final não está bem formatado

Neste exemplo, mostramos o cenário de falha em que o número de telefone do usuário final fornecido está incorreto.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
Resposta: Error : end_user_number is not well-formed
{
    "message": "end_user_number is not well-formed"
}

Código de status:400

Erro : o e-mail do agente não é válido

Neste exemplo, mostramos o cenário de falha em que o e-mail do agente fornecido é inválido.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
Resposta: Erro : o e-mail do agente não é válido
{
    "message": "Not a valid agent email"
}

Código de status:400

Erro : contato não encontrado

Neste exemplo, mostramos o cenário de falha em que o contato fornecido não pôde ser localizado.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "ticket_id": 1,
    "lang": "en"
}
Resposta: erro : contato não encontrado
{
    "message": "Contact not found"
}

Código de status:400

Chamada recebida

Parâmetro Obrigatório Tipo de dados Definição
call_type TRUE String Tipo de chamada a ser criada. Use "Voice Inbound (API)" ou "IncomingCall" (descontinuado) para criar uma chamada recebida.
menu_id TRUE Número inteiro O ID do menu a que a chamada será atribuída. Somente IDs de menu da Web e de URA são aceitos.
end_user_number TRUE String O número de telefone do usuário final que será discado. Se um ticket_id e um end_user_number forem transmitidos, o ticket_id terá precedência.
lang FALSO String Idioma da chamada. Usa códigos ISO 639-1. Padrão: "en"
ticket_id FALSO String ID do tíquete do CRM. O número de telefone do usuário final vinculado ao tíquete será discado. Se um ticket_id e um end_user_number forem transmitidos, o ticket_id terá precedência.
outbound_number FALSO String O número de telefone de saída a ser usado na chamada. O número de telefone global padrão para chamadas externas será usado se a entrada não for transmitida ou for inválida. Os números de saída são gerenciados em Configurações > Fila > EDITAR / VER > Selecionar uma fila > Números de telefone de saída.
recording_permission FALSO String O valor só será avaliado se o recurso "Opções de gravação de chamadas" estiver definido como "Pedir permissão ao usuário para gravar". Configurável em Configurações > Fila > EDITAR / VER > Selecionar uma fila > Opções de gravação de chamadas. Se o valor for "recording_permission_not_asked" (padrão) ou "recording_permission_denied", a chamada não será gravada. Se o valor for "recording_permission_granted", a chamada será gravada.

Endpoint:

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

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "ticket_id": "76517",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}

Exemplo de solicitação e respostas

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

Erro : o número do usuário final não está bem formatado

Neste exemplo, mostramos o cenário de falha em que uma chamada recebida é criada, mas o número do usuário final fornecido está incorreto.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 999-657-12",
    "recording_permission": "recording_permission_granted"
}
Resposta: Error : end_user_number is not well formed
{
    "message": "end_user_number is not well formed"
}

Código de status:400

Erro : o menu está no estado "redirecionamento manual" e não pode aceitar chamadas

Neste exemplo, mostramos o cenário de falha em que uma chamada é encaminhada para um ID de menu, mas o menu está no estado de redirecionamento manual e, portanto, não pode receber chamadas.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Resposta: Erro : o menu está no estado "redirecionamento manual" e não pode aceitar chamadas.
{
    "message": "Menu is in 'manual redirection' state, can't accept calls"
}

Código de status:400

Erro : tipo de chamada inválido

Neste exemplo, mostramos o cenário de falha em que uma chamada recebida é criada, mas o tipo de chamada fornecido é inválido.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "InvalidCallType",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Resposta: Error : Invalid call type
{
    "message": "Invalid call type"
}

Código de status:400

Erro : o ID do menu é obrigatório

Neste exemplo, mostramos o cenário de falha em que uma chamada recebida é criada, mas o ID do menu fornecido é inválido.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Resposta: Error : menu_id is required
{
    "message": "menu_id is required"
}

Código de status:400

Erro : somente IDs de menu móvel e URA são permitidos

Neste exemplo, mostramos o cenário de falha em que uma chamada recebida é criada, mas o ID do menu fornecido não é um ID de URA ou de menu para dispositivos móveis.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 50,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Resposta: Error : Only IVR and mobile menu IDs are permitted
{
    "message": "Only IVR and mobile menu IDs are permitted"
}

Código de status:400

Criar uma chamada recebida com o número do usuário final

Este exemplo demonstra como criar uma chamada recebida com um número de usuário final específico.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+82-10-6861-2345",
    "recording_permission": "recording_permission_granted"
}
Resposta: crie uma chamada recebida com end_user_number
{
    "id": 515,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T00:19:14.000Z",
    "queued_at": "2019-09-10T00:19:14.421Z",
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 820,
            "type": "end_user",
            "status": "waiting",
            "call_id": 515,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T00:19:14.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

Código de status: 201

Erro : o menu está no estado "após o horário de expediente" e não pode aceitar chamadas.

Este exemplo demonstra a falha quando o ID do menu fornecido está no estado after hours.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Resposta: Erro : o menu está no estado "após o expediente", não é possível aceitar chamadas recebidas
{
    "message": "Menu is in 'after hours' state, can't accept incoming calls"
}

Código de status:400

Erro : o idioma não está disponível

Este exemplo demonstra a solicitação de falha quando o idioma especificado não está disponível.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Inbound (API)",
    "lang": "fr",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Resposta: erro : o idioma não está disponível
{
    "message": "Language 'fr' is not available"
}

Código de status:400

Criar uma chamada recebida com o ID do tíquete

Este exemplo demonstra a solicitação para criar uma chamada recebida com um ID de tíquete associado.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "ticket_id": "76517",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Resposta: crie uma chamada recebida com ticket_id
{
    "id": 519,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T05:12:26.000Z",
    "queued_at": "2019-09-10T05:12:26.295Z",
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": "76517",
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 826,
            "type": "end_user",
            "status": "waiting",
            "call_id": 519,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T05:12:26.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

Código de status: 201

Erro : o idioma não foi encontrado

Este exemplo demonstra a falha quando o idioma fornecido não é encontrado.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Inbound (API)",
    "lang": "xy",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Resposta: Error : Language is not found
{
    "message": "Language 'xy' is not found"
}

Código de status:400

Erro : menu_id não encontrado

Este exemplo demonstra a falha quando o ID do menu fornecido não é encontrado.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9999,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Resposta: Error : menu_id is not found
{
    "message": "menu_id 9999 is not found"
}

Código de status:400

Erro : menu_id não está bem formatado

Este exemplo demonstra a falha quando o ID do menu fornecido não está correto.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": "menu_999",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Resposta: Error : menu_id is not well formed
{
    "message": "menu_id is not well formed"
}

Código de status:400

Erro : o número do usuário final é obrigatório

Neste exemplo, mostramos o cenário de falha em que uma chamada recebida é criada, mas o número de telefone do usuário final não foi fornecido.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "recording_permission": "recording_permission_granted"
}
Resposta: Error : end_user_number is required
{
    "message": "end_user_number is required"
}

Código de status:400

Ligação agendada

Parâmetro Obrigatório Tipo de dados Definição
call_type TRUE String Tipo de chamada a ser criada. Use "Voice Scheduled (API)" ou "ScheduledCall" (descontinuado) para criar uma chamada programada.
menu_id TRUE Número inteiro O ID do menu a que a chamada será atribuída. Somente IDs de menu para dispositivos móveis e Web são aceitos.
call_id FALSO Número inteiro ID da chamada anterior, que será vinculada como a chamada principal da nova chamada programada criada. Quando o ID de chamada está sendo usado, o menu_id pode ser opcional.
end_user_number TRUE String O número de telefone do usuário final que será discado. Se um ticket_id e um end_user_number forem transmitidos, o ticket_id terá precedência.
lang FALSO String Idioma da chamada. Usa códigos ISO 639-1. Padrão: "en"
ticket_id FALSO String ID do tíquete do CRM. O número de telefone do usuário final vinculado ao tíquete será discado. Se um ticket_id e um end_user_number forem transmitidos, o ticket_id terá precedência.
scheduled_at TRUE String Horário programado da ligação. Usa o formato ISO 8601 para um horário futuro válido.
recording_permission FALSO String O valor só será avaliado se o recurso "Opções de gravação de chamadas" estiver definido como "Pedir permissão ao usuário para gravar". Configurável em Configurações > Fila > EDITAR / VER > Selecionar uma fila > Opções de gravação de chamadas. Se o valor for "recording_permission_not_asked" (padrão) ou "recording_permission_denied", a chamada não será gravada. Se o valor for "recording_permission_granted", a chamada será gravada.

Endpoint:

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

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "ticket_id": "76517",
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}

Exemplo de solicitação e respostas

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

Erro : end_user_number não está bem formatado

Este exemplo demonstra a falha devido à formatação incorreta do end_user_number.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 999-657-12",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Resposta: Error : end_user_number is not well formed
{
    "message": "end_user_number is not well formed"
}

Código de status:400

Erro : o menu está no estado "redirecionamento manual" e não pode aceitar chamadas

Este exemplo demonstra a falha quando o ID do menu especificado é definido como redirecionamento de menu e não pode aceitar chamadas.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Resposta: Erro : o menu está no estado "redirecionamento manual" e não pode aceitar chamadas.
{
    "message": "Menu is in 'manual redirection' state, can't accept calls"
}

Código de status:400

Erro : tipo de chamada inválido

Este exemplo demonstra a falha quando uma solicitação é feita e o tipo de chamada é inválido.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "InvalidCallType",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Resposta: Error : Invalid call type
{
    "message": "Invalid call type"
}

Código de status:400

Erro : menu_id é obrigatório

Este exemplo mostra a solicitação e a resposta quando um ID de menu não é fornecido, mas é obrigatório.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Resposta: Error : menu_id is required
{
    "message": "menu_id is required"
}

Código de status:400

Erro : somente IDs de menu para dispositivos móveis e Web são permitidos

Este exemplo demonstra uma solicitação que falha quando um ID de menu fornecido não é um ID de menu da Web ou para dispositivos móveis.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 50,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Resposta: Error : Only mobile and web menu IDs are permitted
{
    "message": "Only mobile and web menu IDs are permitted"
}

Código de status:400

Criar uma chamada programada com o ID do menu

Este exemplo demonstra como criar uma chamada programada com um ID de menu específico.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+82-10-6861-2345",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Resposta: crie uma chamada programada com o ID do menu
{
    "id": 515,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T00:19:14.000Z",
    "queued_at": null,
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 820,
            "type": "end_user",
            "status": "waiting",
            "call_id": 515,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T00:19:14.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

Código de status: 201

Criar uma chamada programada com ID de chamada

Este exemplo mostra como criar uma chamada programada com um ID de chamada específico.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "call_id": 514,
    "end_user_number": "+82-10-6861-2345",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Resposta: crie uma chamada programada com o ID da chamada
{
    "id": 515,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T00:19:14.000Z",
    "queued_at": null,
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 820,
            "type": "end_user",
            "status": "waiting",
            "call_id": 515,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T00:19:14.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

Código de status: 201

Erro : o menu está no estado "após o horário de expediente" e não pode aceitar chamadas.

Neste exemplo, mostramos o cenário de falha em que uma chamada programada é criada, mas o menu fornecido está fora do horário de atendimento e, portanto, não pode receber chamadas recebidas.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Resposta: Erro : o menu está no estado "após o expediente", não é possível aceitar chamadas recebidas
{
    "message": "Menu is in 'after hours' state, can't accept incoming calls"
}

Código de status:400

Erro : o idioma não está disponível

Este exemplo demonstra a falha quando o idioma especificado é inválido.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "fr",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Resposta: erro : o idioma não está disponível
{
    "message": "Language 'fr' is not available"
}

Código de status:400

Erro : o idioma não foi encontrado

Neste exemplo, mostramos o cenário de falha em que uma chamada programada é criada, mas o idioma é inválido ou não está disponível.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "xy",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Resposta: Error : Language is not found
{
    "message": "Language 'xy' is not found"
}

Código de status:400

Erro : ID do menu não encontrado

Neste exemplo, mostramos o cenário de falha em que uma chamada programada é criada, mas o ID do menu fornecido é inválido e não foi encontrado.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9999,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Resposta: erro : ID do menu não encontrado
{
    "message": "menu_id 9999 is not found"
}

Código de status:400

Erro : o ID do menu não está bem formado

Neste exemplo, mostramos o cenário de falha em que uma chamada programada é criada, mas o ID do menu fornecido está incorreto.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": "menu_999",
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Resposta: Error : menu_id is not well formed
{
    "message": "menu_id is not well formed"
}

Código de status:400

Erro : o número do usuário final é obrigatório

Neste exemplo, mostramos o cenário de falha em que uma chamada programada é criada, mas o número do usuário final não foi fornecido.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
Resposta: Error : end_user_number is required
{
    "message": "end_user_number is required"
}

Código de status:400

Erro : scheduled_at é obrigatório

Neste exemplo, mostramos o cenário de falha em que uma chamada programada é criada, mas o valor "scheduled at" está ausente, embora seja obrigatório.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
Resposta: Error : scheduled_at is required
{
    "message": "scheduled_at is required"
}

Código de status:400

Receber atributos de dados reservados durante uma chamada

Endpoint

Method: GET
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/calls/: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

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 chamada

Endpoint

Method: PATCH
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/calls/: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"
}

Transmitir parâmetros de dados para agentes virtuais no meio da sessão

Para usar a API Apps e transmitir parâmetros de dados para agentes virtuais no meio de uma sessão de chamada, consulte Transmitir parâmetros de dados para agentes virtuais no meio da sessão.