Endpoints da campanha

Uma campanha se refere a um recurso de discador automático de saída que entra em contato sequencialmente com uma lista de contatos, inicia chamadas de saída e conecta cada contato a um agente disponível. Os endpoints de campanha fornecem acesso a dados relacionados a campanhas, permitindo a recuperação de objetos de campanha e contato.

  • O objeto Campaign representa uma única campanha na plataforma.

  • O objeto Contact representa um contato individual de uma campanha específica.

Os endpoints de campanha permitem que os usuários adicionem, atualizem e excluam contatos de uma campanha existente. Os endpoints disponíveis incluem:

Status do contato da campanha

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

Status do contato da campanha Descrição
Em breve O contato será discado em seguida.
Discando O contato está sendo discado agora.
Na fila A chamada para um determinado contato está na fila.
Conectado O contato está conectado a um agente.
Concluído A chamada foi concluída.
Transferida A chamada foi transferida.
Transferência concluída A chamada foi transferida e concluída.
Não retirado O usuário final não respondeu ou nunca foi contatado.
Não foi possível entrar em contato A chamada nunca chegou ao contato.
Abandonada pelo contato Na prévia, o usuário final desliga antes de se conectar a um agente. Para os dois tipos, o usuário final desliga a chamada em até 5 segundos após se conectar ao agente.
Ignorado O contato foi ignorado pelo agente e estará disponível para ser conectado a outro agente.
Ignorada e fechada Na prévia, o agente pula e encerra um contato. Esse contato sempre será ignorado nessa campanha.
Número inválido Contato com número de telefone inválido.
Erro da transportadora Esse erro é causado pela operadora.
Abandonada pelo Telefone O discador abandonou o contato.
O correio de voz foi desligado No modo preditivo, o discador determina que o usuário final é uma máquina (por exemplo, correio de voz).
Erro geral do discador A chamada falhou devido a um erro no discador.
Ligar de novo programado Status temporário. Rediscagem programada para o futuro.
Não ligar O número estava na lista de bloqueio de ligações.
Número de saída inválido Contato com número de saída inválido.
Número de telefone bloqueado Contato com número internacional inválido/bloqueado.

Adicionar um único contato a uma campanha

Parâmetro Obrigatório Tipo de dados Definição
campaign_id TRUE Número inteiro O ID da campanha a que um contato será adicionado.

Endpoint:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/outbound_dialer/campaigns/{campaign_id}/contacts

Cabeçalhos:

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

Corpo:

{
    "name": "string",
    "email": "customer@somedomain.com",
    "phone_number": "+1 111-111-1111",
    "outbound_number": "+1 760-867-5309",
    "external_unique_id": "UID_123456"
}

Exemplo de solicitação e respostas

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

Adicionar um único contato a uma campanha

Este exemplo mostra como adicionar um contato a um ID de campanha específico.

Solicitação

Cabeçalhos:

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

Consulta

Chave Valor Descrição
campaign_id integer O ID da campanha a que o contato será adicionado

Corpo:

{
    "name": "string",
    "email": "customer@somedomain.com",
    "phone_number": "+1 111-111-1111",
    "outbound_number": "+1 760-867-5309",
    "external_unique_id": "UID_123456"
}
Resposta
{
    "valid_contacts": [
        {
            "name": "string",
            "email": "customer@somedomain.com",
            "phone_number": "+1 111-111-1111",
            "outbound_number": "+1 760-867-5309",
            "external_unique_id": "UID_123456"
        }
    ],
    "invalid_contacts": []
}

Código de status:200

Receber contatos de uma campanha

Parâmetro Obrigatório Tipo de dados Definição
campaign_id TRUE Número inteiro O ID da campanha de onde os contatos serão recuperados.

Endpoint:

Method: GET
Type:
URL: https://{subdomain}.​{domain}​/apps/api/v1/outbound_dialer/campaigns/{campaign_id}/contacts

Cabeçalhos:

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

Consulta

Chave Valor Descrição
campaign_id integer O ID da campanha a que o contato será adicionado

Exemplo de solicitação e respostas

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

Receber contatos de uma campanha

O exemplo a seguir demonstra como recuperar os contatos para o ID da campanha especificado.

Solicitação

Cabeçalhos:

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

Consulta

Chave Valor Descrição
campaign_id integer ID da campanha a ser consultada
Resposta
[
  {
      "name": "string",
      "email": "customer@somedomain.com",
      "phone_number": "+1 111-111-1111",
      "outbound_number": "+1 760-867-5309",
      "external_unique_id": "UID_123456"
  }
]

Código de status:200

Importar vários contatos para uma campanha

Parâmetro Obrigatório Tipo de dados Definição
arquivo TRUE String Arquivo JSON que contém os vários contatos a serem adicionados a uma campanha.
campaign_id TRUE Número inteiro O ID da campanha a que os contatos serão adicionados.

Endpoint:

Method: POST
Type: FORM DATA
URL: https://{​subdomain}​.{​domain}​/apps/api/v1/outbound_dialer/campaigns/{campaign_id}/contacts/import

Cabeçalhos:

Chave Valor Descrição
Content-Type multipart/form-data

Corpo:

'FORM DATA'

Conteúdo do arquivo:

[
  {
      "name": "string",
      "email": "customer@somedomain.com",
      "phone_number": "+1 111-111-1111",
      "outbound_number": "+1 760-867-5309",
      "external_unique_id": "UID_123456"
  }
]

Exemplo de solicitação e respostas

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

Importar vários contatos de um arquivo

Este exemplo demonstra a adição de contatos a uma campanha com base em um arquivo postado no endpoint. O arquivo é postado como dados de formulário.

Solicitação

Cabeçalhos:

Chave Valor Descrição
Content-Type multipart/form-data

Consulta

Chave Valor Descrição
campaign_id integer ID da campanha a que os contatos serão adicionados

Conteúdo do arquivo:

[
  {
      "name": "string",
      "email": "customer@somedomain.com",
      "phone_number": "+1 111-111-1111",
      "outbound_number": "+1 760-867-5309",
      "external_unique_id": "UID_123456"
  }
]
Resposta

None

Código de status:202 (Aceito)

Jobs

Parâmetro Obrigatório Tipo de dados Definição
job_id TRUE Número inteiro O ID do job que você quer recuperar
campaign_id TRUE Número inteiro O ID da campanha a que o ID do trabalho pertence.

Endpoint:

Method: GET
Type:
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/outbound_dialer/campaigns/{campaign_id}/contacts/jobs/{job_id}

Cabeçalhos:

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

Exemplo de solicitação e respostas

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

Concluído com sucesso

O exemplo a seguir demonstra como recuperar o job e identificar se ele foi concluído.

Solicitação

Cabeçalhos:

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

Consulta

Chave Valor Descrição
campaign_id 1 O ID da campanha a que o job pertence
job_id 530 O ID do job para verificar o status
Resposta
{
    "id": 530,
    "status": "completed",
    "type": "Jobs::Bulk::Campaign::ParentJob"
}

Código de status:200

A importação ainda está em andamento

O exemplo a seguir demonstra como recuperar o job e identificar se a importação ainda está em andamento.

Solicitação

Cabeçalhos:

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

Consulta

Chave Valor Descrição
campaign_id 1 O ID da campanha a que o job pertence
job_id 530 O ID do job para verificar o status
Resposta
{
    "id": 530,
    "status": "in_progress",
    "type": "Jobs::Bulk::Campaign::ParentJob"
}

Código de status:200

Job com falha

O exemplo a seguir demonstra como recuperar o job e identificar se ele falhou.

Solicitação

Cabeçalhos:

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

Consulta

Chave Valor Descrição
campaign_id 1 O ID da campanha a que o job pertence
job_id 523 O ID do job para verificar o status
Resposta
{
    "error_details": "NativePowerDial::ContactService::DuplicateContactPhoneOnCampaign",
    "error_message": "Internal Error",
    "id": 523,
    "status": "failed",
    "type": "Jobs::Bulk::Campaign::StartImport"
}

Código de status:200

Atualizar um único contato

Parâmetro Obrigatório Tipo de dados Definição
campaign_id TRUE Número inteiro O ID da campanha a que o ID do trabalho pertence.

Endpoint:

Method: PATCH
Type: RAW
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/outbound_dialer/campaigns/{campaign_id}/contact

Cabeçalhos:

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

Corpo:

{
    "contact_id": 16312,
    "name": "string",
    "email": "customer@somedomain.com",
    "phone_number": "+1 111-111-1111",
    "external_unique_id": "UID_123456"
}

Exemplo de solicitação e respostas

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

Atualizar um contato para uma campanha

Este exemplo mostra como atualizar um contato que está em uma campanha específica.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "contact_id": 7,
    "name": "Bob Smith",
    "email": "customer@somedomain.com",
    "phone_number": "+1 111-111-1111",
    "external_unique_id": "UID_123456"
}
Resposta
{
    "id": 7,
    "name": "Bob Smith",
    "campaign_id": 6,
    "assigned_call_id": null,
    "assigned_participant_id": null,
    "outbound_number": "+1-(201)-471-6992",
    "priority": null,
    "created_at": "2024-08-05T14:51:49.000Z",
    "updated_at": "2024-08-05T21:01:16.000Z",
    "status": "Upcoming",
    "user_custom_metadata": {
        "NAME (REQUIRED)": "Bob Smith",
        "PHONE (REQUIRED)": "+1 111-111-1111",
        "EMAIL (REQUIRED)": "customer@somedomain.com"
    }
}

Código de status:200

Remover um único contato

Parâmetro Obrigatório Tipo de dados Definição
campaign_id TRUE Número inteiro O ID da campanha a que o ID do trabalho pertence.

Endpoint:

Method: DELETE
Type: RAW
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/outbound_dialer/campaigns/{campaign_id}/contact

Cabeçalhos:

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

Corpo:

{
    "contact_id": integer,
    "phone_number": "string",
    "external_unique_id": "string"
}

Exemplo de solicitação e respostas

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

Remover um contato por ID

Este exemplo demonstra como remover um contato de uma campanha com base no ID do contato.

Solicitação

Cabeçalhos:

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

Corpo:

{
    "contact_id": 7,
}

Consulta

Chave Valor Descrição
campaign_id 1 O ID da campanha a que o job pertence
Resposta
{
    "id": 7,
    "name": "Bob Smith",
    "campaign_id": 6,
    "assigned_call_id": null,
    "assigned_participant_id": null,
    "outbound_number": "+1-(201)-471-6992",
    "priority": null,
    "created_at": "2024-08-05T14:51:49.000Z",
    "updated_at": "2024-08-05T21:01:16.000Z",
    "status": "Upcoming",
    "user_custom_metadata": {
        "NAME (REQUIRED)": "Bob Smith",
        "PHONE (REQUIRED)": "+1 111-111-1111",
        "EMAIL (REQUIRED)": "customer@somedomain.com"
    }
}

Código de status:200