Chamar endpoints

Os endpoints de API de chamada 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 de API de chamada:

Objeto de chamada

Veja a seguir 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 da chamada

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 o contact center, mas ainda está navegando pelas opções do menu antes de ser colocado em um menu de folha.
Na fila Estado que ocorre depois que o usuário final seleciona um nó de menu de folha e inicia uma solicitação de chamada para ser transmitida por deltcast ou multicast para um agente.
Atribuído Estado que ocorre quando um agente é selecionado para receber a chamada do usuário final. Isso ocorre quando uma chamada é atendida por um agente.
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 estabelece uma conexão e o agente e o usuário final são colocados em uma chamada.
Concluído Estado que ocorre quando uma chamada é encerrada 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 chamada original. Notas recuperadas de que o retorno de chamada foi concluído sem erros.
Programado Estado que ocorre quando um usuário final programa uma chamada futura usando a Web ou o app.
Somente ação Estado que ocorre quando uma chamada processada pelo provedor de telefonia do cliente é conectada ao nosso SDK do iOS ou SDK do 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 SDK do Android e é concluída
Desviada Estado que ocorre com base na configuração de filas de capacidade excedida ou chamadas fora do horário de atendimento. As opções de desvio incluem correio de voz, agendamento de chamadas, entre outras. A deflexão varia de acordo com o canal (no app, URA, na Web)
Correio de voz Estado que ocorre quando um usuário final é desviado para uma opção de correio de voz e opta por deixar uma mensagem de correio de voz para ser ouvida mais tarde. Esse estado é apresentado quando o usuário final está deixando o correio de voz.
Correio de voz recebido Estado que ocorre depois que um usuário final deixa uma mensagem no correio de voz e um agente não a ouve.
Leitura do correio de voz 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 ser um dos seguintes valores:

Tipo de chamada Descrição
Voz de saída (API) Chamada feita pela API Outbound Call.
Entrada de voz (API) Chamada feita pela API de chamada recebida.
Voice Scheduled (API) Chamada feita pela API Scheduled Call.

Códigos de resposta comuns da API

Confira as respostas mais comuns da API:

Código de resposta Significado
201 A solicitação de API foi bem-sucedida e vai criar uma chamada
202 A solicitação de API foi bem-sucedida, mas é necessária uma intervenção manual no widget para concluir a ação.
400 tipo de chamada inválido: verifique se call_type é aceito
400 O agente não está disponível para atender a esta chamada
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)", "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 de CRM e 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 fazer a ligação. ticket_id tem uma prioridade maior do 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 mostram exemplos de solicitações para o endpoint.

Erro : o agente não está disponível para atender a esta chamada

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

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: Erro : o agente não está disponível para atender a esta chamada
{
    "message": "Agent is not available to take this call"
}

Código de status:400

Criar uma chamada de saída com o número do usuário final

Este exemplo demonstra como fazer uma chamada 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: criar 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 de saída com o ID do tíquete

Este exemplo demonstra a criação de uma chamada de saída 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: criar uma chamada de saída 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 : o ID do tíquete ou o número do usuário final é obrigatório

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 são 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: Erro : ticket_id ou end_user_number obrigatório

{
    "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: Erro : o e-mail do agente é obrigatório

{
    "message": "Agent email required"
}

Código de status:400

Erro : o agente não tem acesso para fazer chamadas

Este exemplo demonstra a falha quando o agente especificado não tem permissão para fazer ligações efetuadas.

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 formado

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: Erro : end_user_number não está bem formado
{
    "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

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

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

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: Erro : tipo de chamada inválido
{
    "message": "Invalid call type"
}

Código de status:400

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

Nesse cenário, o adaptador de chamada é solicitado com 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

Aceito : 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 chamada 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)", "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 de CRM e 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 fazer a ligação. ticket_id tem uma prioridade maior do 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 mostram exemplos de solicitações para o endpoint.

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

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: Erro : ticket_id ou end_user_number obrigatório

{
    "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: Erro : o e-mail do agente é obrigatório
{
    "message": "Agent email required"
}

Código de status:400

Criar uma chamada de saída com o número do usuário final

Neste exemplo, mostramos como criar uma chamada de saída 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: criar 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: Erro : tipo de chamada inválido
{
    "message": "Invalid call type"
}

Código de status:400

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

Neste exemplo, mostramos como solicitar ao adaptador de chamada 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

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

Neste exemplo, mostramos como fazer uma chamada de saída 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 chamadas 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 chamadas de saída. ##### 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 de saída com o ID do tíquete.

Neste exemplo, mostramos o cenário de criação de uma chamada de saída 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: criar uma chamada de saída 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

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

Neste exemplo, mostramos o cenário em que uma solicitação de chamada de saída é 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 a esta chamada

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

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 está disponível para atender a esta chamada
{
    "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 formado

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: Erro : end_user_number não está bem formado
{
    "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 foi 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 Inteiro O ID do menu ao qual a chamada será atribuída. Somente IDs de menus 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 que será usado para a chamada. O número de telefone de saída global padrão 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 / VISUALIZAR > 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 / VISUALIZAR > 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 mostram exemplos de solicitações para o endpoint.

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

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: Erro : end_user_number não está bem formado
{
    "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 recebidas.

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: Erro : tipo de chamada inválido
{
    "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: erro : menu_id é obrigatório
{
    "message": "menu_id is required"
}

Código de status:400

Erro : somente IDs de URA e de menu para dispositivos móveis 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 menu de URA ou de dispositivo móvel.

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: Erro : somente IDs de URA e de cardápio para dispositivos móveis são permitidos
{
    "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: criar 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 "fora do horário de funcionamento" e não pode aceitar chamadas recebidas

Este exemplo demonstra a falha quando o ID do menu fornecido está no estado fora do horário de funcionamento.

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 "fora do horário de funcionamento" e não pode 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: criar 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 : idioma não 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: Erro : idioma não encontrado
{
    "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: erro : menu_id não encontrado
{
    "message": "menu_id 9999 is not found"
}

Código de status:400

Erro : menu_id não está bem formado

Este exemplo demonstra a falha quando o ID do cardápio 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: Erro : menu_id não está bem formado
{
    "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: Erro : end_user_number é obrigatório
{
    "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 agendada.
menu_id TRUE Inteiro O ID do menu ao qual a chamada será atribuída. Somente IDs de cardápios para dispositivos móveis e Web são aceitos.
call_id FALSO Inteiro ID da chamada anterior, que será vinculada como a chamada mãe da nova chamada agendada. Quando o ID da chamada é 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 chamada. 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 / VISUALIZAR > 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 mostram exemplos de solicitações para o endpoint.

Erro : end_user_number não está bem formado

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

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: Erro : end_user_number não está bem formado
{
    "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: Erro : tipo de chamada inválido
{
    "message": "Invalid call type"
}

Código de status:400

Erro : menu_id é obrigatório

Este exemplo demonstra 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: erro : menu_id é obrigatório
{
    "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 cardápio é fornecido, mas não é um ID de cardápio 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: Erro : somente IDs de cardápios para dispositivos móveis e Web são permitidos
{
    "message": "Only mobile and web menu IDs are permitted"
}

Código de status:400

Criar uma chamada programada com o ID do cardápio

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: criar 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 agendada com o ID da chamada

Este exemplo demonstra como criar uma chamada agendada 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: criar uma chamada agendada 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 "fora do horário de funcionamento" e não pode aceitar chamadas recebidas

Neste exemplo, mostramos o cenário de falha em que uma chamada programada é criada, mas o menu fornecido está fora do horário de funcionamento 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 "fora do horário de funcionamento" e não pode 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 : idioma não encontrado

Neste exemplo, mostramos o cenário de falha em que uma chamada agendada é 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: Erro : idioma não encontrado
{
    "message": "Language 'xy' is not found"
}

Código de status:400

Erro : o ID do menu não foi 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 : o ID do menu não foi 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: Erro : menu_id não está bem formado
{
    "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 agendada é 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: Erro : end_user_number é obrigatório
{
    "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 programado 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: Erro : scheduled_at é obrigatório
{
    "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 de apps para 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.