Começando

Visão geral da plataforma

API Endpoint

https://voice-api.zenvia.com/

A plataforma de desenvolvedor da API de Voz da Zenvia fornece tudo o que desenvolvedores precisam para começar a usar as APIs e ampliar a estratégia de comunicação utilizando nossos recursos de voz para efetuar e receber chamadas ou enviar torpedos.

Os guias aqui disponibilizados fornecem ferramentas, recursos, dados e produtos de API para você integrar e estender seus resultados de pesquisas e campanhas.

Links rápidos:

• Inscreva-se para uma conta
• Permissões de conta
• Descubra as APIs que funcionam melhor para você
• Realize seu primeiro teste

Por que usar nossas APIs?

A solução de voz da Zenvia é destinada para desenvolvedores que precisam de uma comunicação automatizada e principalmente integrada com as ferramentas que a sua empresa já possui.

Nossas APIs de fácil utilização oferecem interações e soluções para chamadas e torpedos de voz através de programação direta. Com elas, você tem:

Como a plataforma está organizada

A plataforma de desenvolvedor é organizada por APIs diferentes de acordo com a necessidade de integração.

Reunimos uma seção de introdução diferente para cada uma contendo todas as suas especificidades. Atualmente, nossas APIs são:

Áudio

Essa API permite que você envie um torpedo de voz ou mensagens de voz do tipo áudio para determinados números.

Central Telefônica

Na central telefônica você poderá fazer configurações e retirar relatórios de ramal e URAs.

Fila

A funcionalidade de filas permite a automatização e manipulação de filas de atendimento.

Chamadas

Essa API permite que você crie chamadas, podendo gravar as ligações, agendar e binar o seu próprio número. Também permite gerar relatório de chamadas, derrubar chamadas em andamento, transferir chamadas e avaliar de chamadas.

Composto

A funcionalidade de Envio de Composto, permite que você envie mensagens de voz por telefone misturando gravações de áudio MP3 com TTS e também realize algumas outras funções de central telefônica como coletar DTMF e transferir.

Conferências

Essa API permite criar e receber um ID para realizar chamadas que, ao serem atendidas, conectam-se a essa conferência.

DIDs

A funcionalidade DID (Número de telefone para recebimento de chamadas) permite que você gerencie, adquira ou remova um DID da sua Conta

Gerenciar Contas

Com essa API você pode criar, consultar, alterar e deletar contas filhas, sendo as contas filhas exatamente iguais a qualquer outra conta na Zenvia.

Minha Conta

Essa funcionalidade permite que você visualize seu saldo, monitore suas contas e suas recargas, edite suas contas e configure e visualize seus webhooks.

Bina

Este endpoint permite que você cadastre e valide suas binas para utilizá-las em chamadas e torpedos de voz com o intuito de identificar ao destino que a ligação é sua, independente do número que estiver sendo utilizado para realizar a chamada.

SMS

O SMS permite que você envie mensagens de texto pela nossa API.

TTS Leitura de Texto

A funcionalidade de TTS permite que você nos envie uma mensagem de texto e nosso torpedo de voz irá transformar em áudio.

Verificação (2FA)

A funcionalidade de verificação ou Two Factor Authentication(2FA), envia um código para um número de telefone e depois você pode verificar se o código informado pelo usuário é válido.

Webphone

Consulta a URL do Webphone de um determinado Ramal enviando os parâmetros para pré-configuração

Bibliotecas

Em nosso GitHub você encontra bibliotecas de cliente e de código aberto que podem ajudá-lo a integrar nossas APIs ao seu sistema de forma mais rápida.

• PHP
• Node
• GO
• C#
• Python
• Java
• Ruby

Suporte

Caso você não encontre algum material ou tenha alguma dúvida técnica que não esteja na documentação, entre em contato conosco pelos nossos canais de suporte.

• E-mail: suporte.voz@zenvia.com.
• Chat: na plataforma de Voz da Zenvia.

Visite as páginas específicas de cada API para obter mais informações sobre como começar a utilizá-las.

Áudio	Gerenciar Contas
Central Telefônica	Minha Conta
Fila	Bina
Chamadas	SMS
Composto	TTS Leitura de Texto
Conferências	Verificação (2FA)
DIDs	Webphone

Guia do usuário

Introdução

Os documentos a seguir ajudarão você a interagir com a API REST e começar a utilizar nossos recursos de voz para efetuar ou receber chamadas e enviar torpedos.

Utilizamos o JSON para estruturar nossos dados e um endereço único da API para identificar os serviços e seus respectivos códigos de respostas HTTP.

💡 Usamos serviços de "cross-origin", aceitando interações de qualquer domínio seguro. Portanto, você pode realizar uma requisição para determinado recurso utilizando alguma API Client.

Guia de início: Inscreva-se para uma conta

Você deve começar criando uma conta em nosso site. A inscrição é necessária para testar APIs, integrá-las ao seu sistema ou aplicativo e usufruir dos recursos disponíveis.

Inscreva-se neste link e siga os passos abaixo:

1. Preencha os dados solicitados e clique em Criar conta;
2. Valide seu cadastro através do e-mail e telefone;
3. Acesse o painel.

Na página principal da sua conta, você terá acesso ao Access-Token que será utilizado para autenticação no serviço. Ele estará disponível e localizado conforme sinalizado na imagem:

Permissões de conta

O acesso às APIs de Voz da Zenvia possui uma hierarquia de contas onde cada uma contém suas especificidades.

Ao criar uma nova conta, a mesma é criada automaticamente como Trial. Esse tipo possui limitações que garantem a segurança do negócio, evitando assim que pessoas mal intencionadas utilizem nossos serviços.

Por outro lado, após validar as informações solicitadas (telefone e e-mail), a conta é aprovada instantaneamente. A partir disso, é válido saber:

Tipo de conta	Descrição	Subconta	Limitações
Contas Trial	São contas que ainda não tiveram seus dados confirmados, possuindo o intuito apenas de testar as funcionalidades da API.	X	São limitados ao envio das funções da API apenas números cadastrados e confirmados no painel. Não podem editar ramais. Máximo de 50 SMS enviados por dias, com limitações de palavras bloqueadas por texto. Função de BINA disponível apenas no torpedo de voz com números cadastrados. Não possui acesso à central telefônica.
Contas Cliente	Dá a liberdade para utilização da API com apenas algumas limitações por questão de segurança, como aquelas que evitam golpes ou usam spams.	X	Não podem binar números não sejam seus confirmados. Não podem criar e administrar contas filhas. Máximo de 50 SMS enviados por dia, limite que cresce de acordo com o uso. SMSs com algumas palavras proibidas (referente à cobranças, instituições financeiras, links, etc).
Contas Pai	São contas para quem possui a necessidade de criar e administrar outras contas, como em integrações com sistemas, revenda de serviços e utilização por terceiros das funções de telefonia.	Contas Filhas	As contas Pais têm as mesmas limitações das contas Clientes, tendo apenas o diferencial de poder administrar subcontas. As contas Filhas são basicamente contas criadas através de outra conta, são parecidas com as contas Clientes, tendo os mesmos privilégios, sendo apenas vinculada a uma outra conta, podendo ser Alterada ou Removida por sua conta Pai.

Recursos de desenvolvedor

Autenticação

Este tópico explica como obter e configurar a autorização de token de acesso com a API de Voz, principal e única forma de autenticação que aplicamos.

Esta é a maneira como as APIs de Voz da Zenvia garantem que os dados sejam protegidos.

Sua utilização permite que desenvolvedores legitimem sua conta, acessem as APIs para obter informações e realizem as demais requisições desejadas.

Sobre Tokens de Acesso

Exemplo de autenticação

$ curl https://voice-api.zenvia.com/sms \
    --header 'Access-Token: testeM68PU1Izmb9chEdLzep7IwRymWO'

<?php
$client = new TotalVoiceClient('testeM68PU1Izmb9chEdLzep7IwRymWO');

const totalvoice = require('totalvoice-node');
const client = new totalvoice("testeM68PU1Izmb9chEdLzep7IwRymWO");

client := totalvoice.NewTotalVoiceClient("testeM68PU1Izmb9chEdLzep7IwRymWO")

from totalvoice.cliente import Cliente
client = Cliente("testeM68PU1Izmb9chEdLzep7IwRymWO", 'voice-api.zenvia.com')

TotalVoiceClient client = new TotalVoiceClient("testeM68PU1Izmb9chEdLzep7IwRymWO");

IMPORTANTE: Não esqueça de alterar o Access-Token de exemplo pelo seu token.

A autorização do token de acesso permite que você, desenvolvedor, acesse as APIs para obter informações da sua conta e realize as chamadas que desejar, bastando apenas utilizar o código como parâmetro.

Exemplo de Access-Token:

testeM68PU1Izmb9chEdLzep7IwRymWO

Geração do Access-Token

Após criar a sua conta na plataforma, você pode realizar o login aqui e ter acesso ao seu token da API.

No canto inferior esquerdo da tela inicial, clique no ícone de Copiar em Access Token.

Importante: Lembre-se de copiar e colar o token em um local seguro e mantê-lo em segredo. Recomendamos também não utilizá-lo em código público e nem compartilhá-lo com ninguém fora da sua organização.

Requisições

O código de autenticação retornado na etapa anterior servirá como um ticket de acesso para os serviços disponíveis nas nossas APIs.

Dessa forma, o Token será validado sempre que uma requisição for feita e você deve utilizar o mesmo para cada uma delas.

💡 Lembre-se que as requisições podem ser para áudios, centrais telefônicas, chamadas, entre outras.

Solicitações

As APIs da Zenvia são baseadas no padrão REST e formato JSON para receber e retornar os dados. Esses recursos são acessados através de solicitações HTTP por meio do seguinte caminho:

Cabeçalho de solicitação de autorização HTTP

O token deve ser enviado nas requisições através do header padrão do protocolo HTTP.

Toda e qualquer requisição precisa conter em seu cabeçalho (header) o seu código de autenticação (Access-Token), que será utilizado para identificação na plataforma.

💡 Desenvolvedores não necessitam lidar com as complexidades relacionadas à autenticação. As bibliotecas disponibilizadas pela ZenAPI já fazem a autenticação na requisição HTTP de forma transparente e automática.

🔐 Mantenha seu Token em segredo, tome muito cuidado, não deixe ele exposto em um código público e nunca compartilhe com ninguém fora da sua organização.

Respostas de API

Exemplo JSON de retorno

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "áudio criado com sucesso",
  "dados": {
    "id": 4921
  }
}

As respostas das APIs vêm em formato JSON contendo:

• Cabeçalho padrão;
• Cabeçalho com as informações sobre a requisição;
• Dados próprios da resposta, localizado no campo dados.

status integer	Código HTTP da resposta.
sucesso boolean	Sucesso ou falha da requisição.
motivo integer	Código do motivo da falha ou sucesso.
mensagem string	Mensagem de resposta contendo mensagem sucesso ou motivo de falha.
dados object	Objeto de resposta variável em cada função da API.

Códigos HTTP

Códigos HTTP utilizados

200	Os dados foram retornados com sucesso.
400	Formato do JSON enviado é inválido.
402	Sua conta não tem saldo suficiente.
403	Sua conta não tem permissão para realizar esse procedimento.
404	Objeto de sua pesquisa não foi encontrado.
405	Algum dos parâmetros enviados está inválido
429	Limite de Requisições por segundo excedido
500	Alguma coisa aconteceu internamente.
501	Ainda não implementamos essa funcionalidade (?).

As respostas das requisições realizadas para a API de Voz utilizam os códigos convencionais HTTP.

Elas podem indicar sucesso ou falha, onde:

• O código 200 responde pelo sucesso;
• Códigos que iniciam por 4xx respondem pelas falhas.
• Códigos começando com 5xx respondem pelas falhas internas.

Códigos de Motivos

Códigos de Motivos

0	Os dados foram retornados com sucesso.
8	Sua conta não tem permissão para realizar esse procedimento.
9	Sua conta não tem saldo suficiente.
10	Você não enviou todos os parâmetros obrigatórios.
11	Algum dos parâmetros enviados está inválido.
20	Erro porque o registro ficaria duplicado.
30	Esta funcionalidade ainda não foi implementada. (Entre em contato)
40	Houve uma falha na autenticação, seu Token está correto?
50	Erro interno dentro do nosso sistema.
60	Não encontramos o elemento que você está procurando.
70	A chamada requisitada não contém uma gravação.
80	A chamada solicitada não está ativa.
90	O caminho não foi encontrado.
100	A requisição solicitada é inválida.

Um dos parâmetros padrões que vêm em toda resposta da API é o motivo. É nele onde detalhamos o motivo pelo qual a sua requisição falhou (ou deu certo).

Ao lado, a tabela detalha a lista de motivos possíveis e mais detalhes seguem no campo mensagem do cabeçalho.

💡 Utilize o atributo sucesso se for apenas para identificar se a requisição deu certo ou não.

Status para Chamada

Status para Chamada

atendida	A ligação foi atendida.
sem resposta	O número não atendeu a ligação.
ocupado	A operadora retornou que o número estava ocupado.
congestionado	Houve algum problema nas linhas de conexões. (Entre em contato)
falha	Não foi possível realizar a ligação.
cancelada	A ligação foi cancelada.
não existe	O número desta ligação não existe.

Ao fim de toda ligação, a chamada terá um status.

Ao lado, a tabela detalha a lista dos possíveis status. Caso encontre um status diferente dos mapeados, entre em contato com a nossa equipe.

Status Perna de Ligação

Status Perna de Ligação

preparando	A ligação para esta perna ainda não foi iniciada.
chamando	O telefone/ramal desta perna está chamando mas não atendeu.
atendida	A perna atendeu a ligação.
ocupado	A operadora retornou que o número estava ocupado no momento.
desconhecido	Houve alguma falha, entrar em contato com o suporte.

Este caso geralmente se refere às ligações de duas pernas, onde primeiramente é disparada uma chamada para perna A (origem) e, quando esta perna atende, a ligação é disparada a para perna B (destino).

Este parâmetro é retornado nos objetos que representam algum lado (perna) de uma ligação que foi realizada.

Por exemplo: em um Objeto de um Áudio haverá um único atributo deste que representa o status do número que ele foi enviado. Por outro lado, em uma Chamada você terá um status para cada uma das pernas dela.

Testes

Com uma conta criada, é possível realizar testes em nossa plataforma utilizando nosso playground ou em um software para teste de requisições de API, como Postman e Insomnia.

Veja mais detalhes sobre:

• Playground: Utilize o token da sua conta e faça envios para nossa API. Para isso, basta preencher um formulário com os parâmetros necessários.

• Postman ou Insomnia: Para utilizar o software de testes, será necessário que você envie as seguintes informações:

  1. Header:
     • Access-Token - exemplotesteM68PU1Izmb9chEdLzep7IwRymWO
     • Content-Type - application/json
  2. Body:
     • No corpo da requisição você deve enviar um JSON (para requisições POST/PUT)

• Para testar os retornos enviados via webhooks, indicamos os seguintes sites:

  1. webhook.site
  2. requestbin.com

APIs de Voz

À medida em que for rolando para baixo nesta documentação, você verá todas as amostras de código de cada API. Verá também exemplos de solicitações e respostas.

Desenvolva soluções de comunicação personalizadas com as APIs de Voz apresentadas a seguir.

Tendo uma plataforma web e móvel, será possível implementar nossos recursos rápidos e seguros para uma experiência que conecta empresa e cliente.

• Experiências de chamadas;
• Notificações automáticas de voz;
• Identificação de padrões de chamada;
• Comunicações de voz text-to-speech;
• Mensagens de texto transformadas em voz;
• Chamadas com maior qualidade e confiança.

Logo abaixo você encontrará uma lista de todos os métodos disponíveis para a API de Voz.

❗ É necessário criar uma conta para usar as APIs. Clique aqui para este primeiro passo.

URL base:

https://voice-api.zenvia.com

Escolha qual API melhor atende sua necessidade de integração e implemente com total confiança:

1. APIs de Central
2. APIs de Contas
3. APIs de Ligações
4. APIs de Torpedos

Verificação (2FA)

Verificação (2FA) Endpoint

https://voice-api.zenvia.com/verificacao

A funcionalidade de verificação ou Two Factor Authentication(2FA) envia um código para um número de telefone e, em seguida, você pode verificar se o código informado pelo usuário é válido.

Esse código (apenas números) pode ser enviado via SMS (formato de texto), ou então TTS onde você nos passa a mensagem que o usuário que atender a ligação irá ouvir.

Exemplos:

• Mensagem enviada: Seu código de verificação nome_produto é: 1234

• Observação: O código enviado para o número de telefone expira em 1 hora.

Enviar código

Definição

POST https://voice-api.zenvia.com/verificacao

Request

curl -X POST --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: seu-token' \
             -d '{"numero_destino":"+5510999999999","nome_produto":"ZenAPI de Voz","tts":"true"}' \
             'https://voice-api.zenvia.com/verificacao'

<?php
require_once "vendor/autoload.php";
use TotalVoice\Client as TotalVoiceClient;

$client = new TotalVoiceClient('seu-token');
$response = $client->verificacao->enviar('+5510999999999', 'ZenAPI de Voz');

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.verificacao.enviar("+5510999999999", "ZenAPI de Voz")
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.verificacao.enviar("+5510999999999", "ZenAPI de Voz", false, "")

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.verificacao.enviar("+5510999999999", "ZenAPI de Voz")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Verificacao verificacao = new Verificacao(client);

JSONObject response = verificacao.enviar("+5510999999999", "ZenAPI de Voz");

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.verificacao.enviar("+5510999999999", "ZenAPI de Voz")

Response

{
    "status": 200,
    "sucesso": true,
    "motivo": 0,
    "mensagem": "dados retornados com sucesso",
    "dados": {
        "id": 12345
    }
}

Para enviar um código, basta informar o número de destino seguindo o exemplo de requisição ao lado. Utilize os campos abaixos para informar à nossa API os dados que irá enviar:

POST: https://voice-api.zenvia.com/verificacao

REQUEST:

• Headers

Content-Type: application/json Authorization: Access-Token: seu-token

Request

numero_destino Obrigatório	Número do telefone que irá receber o código, via sms ou tts.
nome_produto Obrigatório	Nome do produto que será substituído na mensagem.
tamanho Opcional	Tamanho do código que será enviado. Mínimo 4 e máximo 10, o código possui apenas números. Caso não seja informado, é utilizado o valor default = 4.
tts Opcional	Para que o código de verificação seja enviado por uma ligação (TTS) ao invés de um SMS, basta enviar esse parâmetro como "true". Quando o parâmetro não for enviado, é considerado o valor default "false".

Response

id integer

Retorna o ID de verificação do código enviada.

Consultar código

Definição

GET https://voice-api.zenvia.com/verificacao

Request

curl -X GET --header 'Content-Type: application/json' \
            --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' 'https://voice-api.zenvia.com/verificacao/?id=1234&pin=36355'

<?php
Em Construção

Em Construção

Em Construção

Em Construção

Em Construção

Em Construção

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "resultado": "valido"
  }
}

Após o envio do código, você pode pedir para o usuário inserir na sua plataforma o código recebido para que você possa validar o número dele.

Utilize os campos abaixos para informar à nossa API os dados que irá enviar:

GET: https://voice-api.zenvia.com/verificacao

REQUEST:

• Headers

Content-Type: application/json Authorization: Access-Token: seu-token

Request

id Obrigatório	ID da verificação enviada
pin Obrigatório	Código informado

Response

dados object

Retorna o 'resultado' da verificação, o resultado pode ser 'válido' ou 'inválido'

Webhooks

As notificações de Webhooks são enviadas para seu Endpoint cadastrado no nosso Painel de Voz. A cada evento ocorrido, uma notificação é disparada.

O método utilizado para o envio dos Webhooks é HTTP POST e as informações referentes ao evento vão no corpo da requisição em formato JSON.

Configurar webhook

1. Para configurar o Webhook, siga os seguintes passos:
2. Entre no Painel de Voz com a conta administradora;
3. Acesse o menu Desenvolvedores na barra superior;
4. Escolha Configurações da API
5. Preencha os campos solicitados na criação de cada Webhook.

Webhooks disponíveis

A seguir, você terá acesso às documentações dos Webhooks disponíveis. São eles:

• Eventos em Tempo Real de Chamada
• Eventos em Tempo Real de Ramal
• Eventos em Tempo Real de Chamada DID
• Eventos em Tempo Real de Conferências
• Envio de SMS
• Resposta de SMS
• Aviso de saldo
• Novo Voicemail
• Status Tempo Real
• TTS - Fim de chamada
• Chamada- Fim
• DID- Fim de Chamada
• Composto- Fim de Chamada
• Áudio- Fim de chamada

Eventos em Tempo Real das Chamadas

JSON

\\Chamando Perna A

{
  "data_criacao": "2019-09-06T17:21:33",
  "origem": {
    "data_inicio": "2019-09-06T14:21:33",
    "tipo": "movel",
    "ativo": false,
    "data_criacao": "2019-09-06T14:21:34",
    "numero": "+5510999999999",
    "status": "chamando"
  },
  "gravar_audio": false,
  "id": 37794869,
  "destino": {
    "tipo": "movel",
    "numero": "+5510999999999"
  },
  "cliente_id": 2150,
  "tags": ""
}

Esse Webhook é enviado sempre que uma das pernas de uma chamada muda de estado.

Os atributos são:

Atributos

data_criacao datetime	Data e hora em que a ligação foi criada.
gravar_audio boolean	Se a chamada foi gravada ou não.
id integer	Identificador único desta Chamada.
cliente_id integer	Identificador único (na ZenAPI) do cliente que realizou a Chamada.
tags string	Campo de tags que pode ser utilizado pelo cliente na hora da criação da Chamada.
origem object	Objeto da perna de origem da Chamada.
destino object	Objeto da perna de destino da Chamada.

Eventos em Tempo Real de Ramal

JSON

{
  "data_atendimento": "2019-09-06T14:37:03",
  "duracao_falada_segundos": 10,
  "ativo": false,
  "data_criacao": "2019-09-06T14:36:55",
  "tipo": "ramal",
  "motivo_desconexao": "indefinido",
  "id": "37806158",
  "ramal": 9000,
  "status": "atendida",
  "duracao_segundos": 18
}

Esse Webhook é enviado a cada mudança de status de alguma chamada de um Ramal, enviando seus dados de chamada.

Os atributos são:

Atributos

data_criacao datetime	Data e hora em que a ligação para o Ramal foi criada.
id integer	Identificador único desta ligação.
tipo string	O tipo do telefone desta perna, vem sempre ramal.
ativo boolean	Informa se a chamada está ativa, caso true, o ramal atendeu e a ligação ainda está conectada.
ramal integer	O número do Ramal desta ligação.
status string	Representa o status atual desta perna na ligação.
data_atendimento datetime	Data e hora do momento em que a ligação foi atendida, caso a ligação não tenha sido atendida este atributo não vem.
duracao_segundos integer	Duração total em segundos da ligação, desde a criação até o encerramento (seja por desligar ou por não atender).
duracao_falada_segundos integer	Duração em segundos contados a partir do momento que o ramal atendeu a ligação, até o momento em que foi desligada.
motivo_desconexao String	Aqui é informado o motivo do derrubamento da ligação, você pode ver mais em motivos de desconecção.

Eventos em Tempo Real de Chamada DID

JSON

{
  "data_atendimento": "2019-09-06T14:37:03",
  "duracao_falada_segundos": 0,
  "ativo": true,
  "data_criacao": "2019-09-06T14:36:55",
  "tipo": "ramal",
  "id": "37806158",
  "ramal": 9000,
  "status": "atendida",
  "duracao_segundos": 7
}

Esse Webhook é enviado a cada mudança de status de alguma chamada recebida por um DID, enviando os dados da chamada e do Ramal que atendeu (caso algum tenha atendido).

Os atributos são:

Atributos

id integer	Identificador único desta Chamada.
data_criacao datetime	Data e hora em que a ligação foi criada.
data_atendimento datetime	Data e hora do momento em que a ligação foi atendida pelo DID.
ativo boolean	Informa se a chamada está ativa.
status string	Representa o status atual desta chamada para o DID.
duracao_segundos integer	Duração total da chamada em segundos, desde a criação até o encerramento (seja por desligar ou por não atender).
duracao_falada_segundos integer	Duração em segundos contados a partir do momento que o DID atendeu a ligação até o momento em que foi desligada.
ramal object	Caso a ligação para este DID caia em algum ramal, este campo vem preenchido com informações da perna do ramal.
tipo String	Tipo de telefone: fixo, móvel ou ramal.

Eventos em Tempo Real de Conferências

\\Entrada de número na conferência.

{
  "data_criacao": "2019-09-06T18:48:05",
  "evento_conferencia": "Entrou",
  "numero": "+5510999999999",
  "gravar_audio": false,
  "conferencia_id": 42874,
  "chamada_id": "37823279",
  "cliente_id": 2150
}

Esse Webhook é enviado a cada mudança dentro de uma conferência.

Exemplos: quem entrou ou saiu da conferência, id da chamada, id da conferência e número que entrou.

Atributos

data_criacao datetime	Data e hora em que a conferência foi criada.
gravar_audio boolean	Se a chamada foi gravada ou não.
evento_conferencia String	Informa ação do número/pessoa referente à conferência.
cliente_id integer	Identificador único (na Zenvia) do cliente que executou determinada ação na conferência.
numero String	Número do telefone que executou determinada ação na conferência, formato E.164: [+][DDI][DDD][Número]. Exemplo: +5510999999999.
conferencia_id integer	Identificador único da conferência.
chamada_id String	Identificador único da chamada realizada para a conferência.

Envio de SMS

JSON

{
  "id": "37787430",
  "numero_destino": "+5510999999999",
  "data_criacao": "2019-09-06T14:00:38-03:00",
  "mensagem": "Olá ZenAPI",
  "preco": 0.09,
  "status_envio": "entregue",
  "data_status": "2019-09-06T14:01:13-03:00",
  "resposta_usuario": false,
  "respostas": []
}

Esse Webhook informa se o SMS foi enviado ou se houve falha.

Os atributos são:

Atributos

data_criacao datetime	Data e hora em que o SMS foi criado.
id integer	Identificador único deste SMS.
numero_destino string	Número do telefone que irá receber o SMS, formato E.164: [+][DDI][DDD][Número]. Exemplo: +5510999999999.
mensagem string	Mensagem que será enviada para o número.
preco float	Valor cobrado pelo envio
preco float	Valor cobrado pelo envio
status_envio float	Situação do envio do SMS.
data_status datatime	Data e hora que o status foi alterado.
resposta_usuario boolean	Aguarda a resposta do usuário: sim ou não
respostas boolean	Array contendo os objetos de resposta.

Resposta de SMS

JSON

{ 
   "id":16347,
   "sms_id":133830,
   "resposta":"SIM",
   "data_resposta":"2016-10-17T18:02:20-02:00"
}

Esse Webhook informa quando um usuário responde um SMS.

Os atributos são:

Atributos

id integer	ID do registro de Resposta.
sms_id integer	ID do SMS vinculado a resposta.
resposta string	Texto com a resposta do usuário
data_resposta datetime	Data e hora que foi respondido pelo usuário

Aviso de Saldo

   {
   "saldo":"56.8616"
   }

Esse Webhook informa quando o valor do saldo for inferior ao configurado no "Aviso de Saldo".

Os atributos são:

Atributos

saldo float

Saldo atual da sua conta

Novo Voicemail

  {
  "id": 1411,
  "ramal_id": 87787,
  "ramal": "9561",
  "numero_telefone": "+5510999999999",
  "data_mensagem": "2019-09-06T17:05:18-03:00",
  "duracao_segundos": 0,
  "url_gravacao": "https://api.evoline.com.br/recvm/?id=1411&x=094bba9d3a&cid=2150"
  }

Esse Webhook informa quando houver um novo voicemail (mensagem de voz) na caixa postal.

Atributos

id integer	Identificador único deste voicemail.
ramal_id integer	ID do ramal, o qual irá receber o voicemail.
numero_telefone string	Número do telefone que irá enviar o voicemail para o ramal, formato E.164: [+][DDI][DDD][Número]. Exemplo: +5510999999999.
data_mensagem datatime	Data e hora em que o voicemail foi recebido.
duracao_segundos integer	Duração total do voicemail em segundos.
url_gravacao string	Quando enviado a opção Gravar Áudio = true, este campo disponibilizará uma URL contendo o áudio da gravação da ligação.

Status Tempo Real

JSON

\\Chamando

{
  "id": 37785949,
  "data_criacao": "2019-09-06T13:48:19-03:00",
  "ativa": true,
  "url_gravacao": null,
  "cliente_id": 91227,
  "conta_id": 91227,
  "ramal_id_origem": 86453,
  "tags": null,
  "status_geral": "curso",
  "origem": {
    "data_inicio": null,
    "numero": "4000",
    "tipo": "ramal",
    "status": "chamando",
    "duracao_segundos": 10,
    "duracao": "00:00:10",
    "duracao_cobrada_segundos": null,
    "duracao_cobrada": null,
    "duracao_falada_segundos": null,
    "duracao_falada": null,
    "preco": null,
    "motivo_desconexao": "indefinido"
  },
  "destino": {
    "data_inicio": null,
    "numero": "+5510999999999",
    "tipo": "movel",
    "status": "preparando",
    "duracao_segundos": 9,
    "duracao": "00:00:09",
    "duracao_cobrada_segundos": null,
    "duracao_cobrada": null,
    "duracao_falada_segundos": null,
    "duracao_falada": null,
    "preco": null,
    "motivo_desconexao": "indefinido"
  },
  "gravacoes_parciais": []
}

Durante uma chamada, este webhook é acionado sempre que o status mudar (de "chamando" para "atendido", por exemplo).

Atributos

id integer	ID do registro da chamada.
data_criacao datetime	Data de criação do registro da chamada. Data e Hora no formato UTC.
ativa boolean	Identifica se a chamada está ativa ou não.
url_gravacao string	URL com áudio da gravação da chamada.
cliente_id integer	Identificação do cliente referente a chamada.
conta_id integer	Identificação da Conta referente a chamada.
ramal_id_origem integer	ID do ramal que originou a chamada referente a ligação, se houver.
tags string	Informação adicional que pode ser retornada no objeto, como um ID Externo por exemplo. Você consegue enviar essa informação no Post da Chamada e recuperar posteriormente nessa consulta.
status_geral string	Status geral da Chamada. criada: chamada foi criada curso: está em andamento finalizada: chamada foi finalizada
origem / destino object	Retorna os objetos origem/destino

TTS - Fim de Chamada

JSON

{
  "id": 37784550,
  "numero_destino": "+5510999999999",
  "data_criacao": "2019-09-06T13:34:57.000-03:00",
  "data_inicio": "2019-09-06T13:34:58.000-03:00",
  "tipo": "movel",
  "status": "atendida",
  "duracao_segundos": 17,
  "duracao": "00:00:17",
  "duracao_cobrada_segundos": 60,
  "duracao_cobrada": "00:01:00",
  "duracao_falada_segundos": 10,
  "duracao_falada": "00:00:10",
  "preco": 0.35,
  "resposta_usuario": false,
  "resposta": "",
  "motivo_desconexao": "16. normal",
  "mensagem": "Ôôôôoooooooolááaaaaaaaaaa"
}

Esse Webhook é enviado ao fim de toda chamada TTS, enviando detalhes como duração e status.

Atributos

id integer	ID do registro do TTS.
numero_destino string	Número do destinatário que foi enviado o TTS.
data_criacao datetime	Data e hora que foi criado o registro.
data_inicio datetime	Data e hora que foi iniciado o processamento do TTS.
tipo string	Tipo de telefone: fixo, móvel ou ramal.
status string	Status do registro.
duracao_segundos integer	Duração total em segundos da chamada, desde o início do processamento.
duracao integer	Duração total da chamada desde o início do processamento
duracao_cobrada_segundos integer	Duração em segundos para fins de cobrança.
duracao_cobrada integer	Duração considerada para fins de cobrança.
duracao_falada_segundos integer	Duração em segundos da chamada desde que o destino atendeu.
duracao_falada integer	Duração da chamada desde que o destino atendeu.
preco float	Valor cobrado pela chamada.
mensagem float	Mensagem em forma de texto que você nos enviou.
resposta_usuario boolean	Valor enviado identificando se aceita a resposta do usuário.
resposta string	Se você enviou resposta_usuario = true, quando o usuário executa alguma ação no teclado númerico do dispositivo, o valor será exibido neste campo (DTMF).
motivo_desconexao string	Aqui é informado o motivo do derrubamento da ligação, você pode ver mais em motivos de desconecção

Chamada - Fim

JSON

{
  "id": 37721262,
  "data_criacao": "2019-09-06T11:19:11-03:00",
  "ativa": false,
  "url_gravacao": "https://api.evoline.com.br/rec/?id=37721262&x=7a8718b28b&cid=2150",
  "cliente_id": 2150,
  "conta_id": 2150,
  "ramal_id_origem": 62291,
  "tags": null,
  "status_geral": "finalizada",
  "origem": {
    "data_inicio": null,
    "numero": "9998",
    "tipo": "ramal",
    "status": null,
    "duracao_segundos": 0,
    "duracao": "00:00:00",
    "duracao_cobrada_segundos": 0,
    "duracao_cobrada": "00:00:00",
    "duracao_falada_segundos": 0,
    "duracao_falada": "00:00:00",
    "preco": 0,
    "motivo_desconexao": "indefinido"
  },
  "destino": {
    "data_inicio": "2019-09-06T11:19:11-03:00",
    "numero": "+5510999999999",
    "tipo": "movel",
    "status": "atendida",
    "duracao_segundos": 24,
    "duracao": "00:00:24",
    "duracao_cobrada_segundos": 60,
    "duracao_cobrada": "00:01:00",
    "duracao_falada_segundos": 14,
    "duracao_falada": "00:00:14",
    "preco": 0.35,
    "motivo_desconexao": "16. normal"
  },
  "gravacoes_parciais": []
}

Esse Webhook é enviado ao fim de toda chamada, enviando detalhes como duração e preço.

id integer	ID do registro da chamada.
data_criacao datetime	Data de criação do registro da chamada. Data e Hora no formato UTC.
ativa boolean	Identifica se a chamada está ativa ou não.
url_gravacao string	URL com áudio da gravação da chamada.
cliente_id integer	Identificação do cliente referente a chamada.
conta_id integer	Identificação da Conta referente a chamada.
ramal_id_origem integer	ID do ramal que originou a chamada referente a ligação, se houver.
tags string	Informação adicional que pode ser retornada no objeto, como um ID Externo por exemplo. Você consegue enviar essa informação no Post da Chamada e recuperar posteriormente nessa consulta.
status_geral string	Status geral da Chamada. criada: chamada foi criada curso: está em andamento finalizada: chamada foi finalizada
origem / destino object	Retorna os objetos origem/destino

DID - Fim de Chamada

JSON

{
  "id": 37721125,
  "data_criacao": "2019-09-06T11:18:20-03:00",
  "ativa": false,
  "url_gravacao": "https://api.evoline.com.br/rec/?id=37721125&x=7a020a1a16&cid=2150",
  "cliente_id": 2150,
  "conta_id": 2150,
  "ramal_id_origem": 62291,
  "tags": null,
  "status_geral": "finalizada",
  "origem": {
    "data_inicio": null,
    "numero": "9998",
    "tipo": "ramal",
    "status": null,
    "duracao_segundos": 0,
    "duracao": "00:00:00",
    "duracao_cobrada_segundos": 0,
    "duracao_cobrada": "00:00:00",
    "duracao_falada_segundos": 0,
    "duracao_falada": "00:00:00",
    "preco": 0,
    "motivo_desconexao": "indefinido"
  },
  "destino": {
    "data_inicio": "2019-09-06T11:18:19-03:00",
    "numero": "+5510999999999",
    "tipo": "movel",
    "status": "ocupado",
    "duracao_segundos": 31,
    "duracao": "00:00:31",
    "duracao_cobrada_segundos": 0,
    "duracao_cobrada": "00:00:00",
    "duracao_falada_segundos": 0,
    "duracao_falada": "00:00:00",
    "preco": 0,
    "motivo_desconexao": "indefinido"
  },
  "gravacoes_parciais": []
}

Esse Webhook é enviado ao fim de toda chamada recebida (DID), enviando detalhes como duração e status.

Atributos

id integer	ID do registro da chamada.
data_criacao datetime	Data de criação do registro da chamada. Data e Hora no formato UTC.
ativa boolean	Identifica se a chamada está ativa ou não.
url_gravacao string	URL com áudio da gravação da chamada.
cliente_id integer	Identificação do cliente referente a chamada.
conta_id integer	Identificação da Conta referente a chamada.
ramal_id_origem integer	ID do ramal que originou a chamada referente a ligação, se houver.
tags string	Informação adicional que pode ser retornada no objeto, como um ID Externo por exemplo. Você consegue enviar essa informação no Post da Chamada e recuperar posteriormente nessa consulta.
status_geral string	Status geral da Chamada. criada: chamada foi criada curso: está em andamento finalizada: chamada foi finalizada
origem / destino object	Retorna os objetos origem/destino

Composto - Fim de Chamada

JSON

{
  "id": 37850704,
  "numero_destino": "+5510999999999",
  "data_criacao": "2019-09-06T16:38:50.000-03:00",
  "data_inicio": "2019-09-06T16:38:55.000-03:00",
  "tipo": "movel",
  "status": "atendida",
  "duracao_segundos": 51,
  "duracao": "00:00:51",
  "duracao_cobrada_segundos": 60,
  "duracao_cobrada": "00:01:00",
  "duracao_falada_segundos": 42,
  "duracao_falada": "00:00:42",
  "preco": 0.38,
  "resposta_usuario": false,
  "resposta": null,
  "motivo_desconexao": "16. normal",
  "url_gravacao": null,
  "tags": "clienteX"
}

Ao fim de toda chamada do tipo Composto, um callback é feito para este endereço, enviando detalhes como duração e status.

Atributos

id integer	ID do registro de Áudio.
numero_destino string	Número do destinatário que foi enviado o áudio.
data_criacao datetime	Data e hora que foi criado o registro
data_inicio datetime	Data e hora que foi iniciado o processamento do áudio
tipo string	Tipo de telefone: fixo, móvel ou ramal
status string	Status do registro
duracao_segundos integer	Duração em segundos (inteiro) do total da chamada desde o início do processamento
duracao integer	Duração total da chamada desde o início do processamento
duracao_cobrada_segundos integer	Duração em segundos para fins de cobrança
duracao_cobrada integer	Duração considerada para fins de cobrança
duracao_falada_segundos integer	Duração em segundos da chamada desde que o destino atendeu
duracao_falada integer	Duração da chamada desde que o destino atendeu
preco float	Valor cobrado pela chamada
resposta_usuario boolean	Aguarda a resposta do usuário: sim ou não
resposta string	Quando o usuário executa alguma ação no teclado do dispositivo, o valor será exibido neste campo (DTMF).
url_gravacao string	Quando enviado a opção Gravar Áudio = true, este campo disponibilizará uma URL contendo o áudio da gravação da ligação.
tags string	Parâmetro de integração - informado no post e retornado no get. Ex: "clienteX"
motivo_desconexao string	Um dos motivos de desconexão: 1. telefone não existe 2. sem rota para a rede de destino 3. sem rota para o destino 4. prefixo incorreto 6. canal inaceitável 7. chamada sendo entregue em canal já estabelecido 8. call peemption 14. telefone portado para outra operadora 16. normal 17. ocupado 18. sem resposta 19. sem resposta - mas chamou 20. assinante ausente 21. chamada rejeitada 22. este número mudou 23. redirecionado para novo destino 26. atendido em outro lugar 27. destino não está funcionando 28. formato inválido de número 29. rejeitado 30. resposta para status enquiry 31. normal, não especificado 34. sem canal disponível 41. falha temporária 42. equipamento congestionado 44. canal requisitado não está disponível 50. não cadastrado 52. chamada sainte barrada 54. chamada entrante barrada 57. capacidade não autorizada 58. erro de mídia ou parâmetros incompatíveis 65. capacidade do portador não implementada 66. tipo de canal não implementado 69. não implementado 81. valor de referência inválido 88. destino incompatível 95. mensagem inválida não especificada 96. informação obrigatória não presente 97. mensagem não implementada 98. mensagem não compatível com o estado da chamada ou não existente ou não implementada 97. mensagem não implementada 99. elemento não existente ou não implementado 97. mensagem não implementada 100. informação inválida no conteúdo dos elementos 101. mensagem não compatível com o estado da chamada 102. timeout 111. erro de protocolo 127. erro de conectividade

Áudio - Fim de Chamada

JSON

{
  "id": 37785542,
  "numero_destino": "+5510999999999",
  "data_criacao": "2019-09-06T13:44:52.000-03:00",
  "data_inicio": "2019-09-06T13:44:52.000-03:00",
  "tipo": "movel",
  "status": "atendida",
  "duracao_segundos": 44,
  "duracao": "00:00:44",
  "duracao_cobrada_segundos": 60,
  "duracao_cobrada": "00:01:00",
  "duracao_falada_segundos": 25,
  "duracao_falada": "00:00:25",
  "preco": 0.35,
  "resposta_usuario": false,
  "resposta": "",
  "motivo_desconexao": "16. normal",
  "url_gravacao": null,
  "url_audio": "https://65381g.ha.azioncdn.net/7/7/b/3/daniellimaofficial-never-enough-72a13242.mp3"
}

Ao fim de toda chamada de áudio, um callback é feito para este endereço, enviando detalhes como duração e status.

Atributos

id integer	ID do registro de Áudio.
numero_destino string	Número do destinatário que foi enviado o áudio.
data_criacao datetime	Data e hora que foi criado o registro.
data_inicio datetime	Data e hora que foi iniciado o processamento do áudio.
tipo string	Tipo de telefone: fixo, móvel ou ramal.
status string	Status do registro.
duracao_segundos integer	Duração em total em segundos, da chamada, desde o início do processamento.
duracao String	Duração total da chamada desde o início do processamento
duracao_cobrada_segundos integer	Duração em segundos para fins de cobrança.
duracao_cobrada String	Duração considerada para fins de cobrança.
duracao_falada_segundos integer	Duração em segundos da chamada desde que o destino atendeu.
duracao_falada String	Duração da chamada desde que o destino atendeu.
preco float	Valor cobrado pela chamada.
url_audio string	URL do Áudio enviado para a chamada.
resposta_usuario boolean	Valor enviado identendificando se aceita a resposta do usuário.¹
resposta string	Se você enviou resposta_usuario = true, quando o usuário executa alguma ação no teclado númerico do dispositivo, o valor será exibido neste campo (DTMF).¹
motivo_desconexao string	Aqui é informado o motivo do derrubamento da ligação, você pode ver mais em motivos de desconexão
url_gravacao string	Quando enviado a opção Gravar Áudio = true, este campo disponibilizará uma URL contendo o áudio da gravação da ligação.

APIs de Central

As APIs de Central viabilizam a criação de uma operação de telefonia básica para empresas.

Isso significa que nossas soluções permitem elaborar uma estrutura de telefonia com base nos setores, onde cada um pode possuir um ramal específico, por exemplo.

Além disso, outras funcionalidades são:

• Criar URA para receber ligação;
• Formar grupos de atendimentos (filas);
• Cadastrar e configurar telefones para BINA.

APIs de Central:

• Fila
• Bina
• Número de telefone (DIDs)

💡Inicie o teste rápido aqui

Bina

Bina Endpoint

https://voice-api.zenvia.com/bina

Usando esse recurso, será possível utilizar números de telefone específicos para suas chamadas e torpedos de voz.

Você poderá se identificar ao destino confirmando que a ligação é sua, independente do número ou ramal que estiver sendo utilizado para realizar a chamada.

💡 Bina é o número identificador do telefone de origem e que aparece no telefone do destino.

Para utilizar uma bina específica, é necessário realizar a contratação de um número com a Zenvia.

Objeto Bina

JSON

{
    "id": 432,
    "numero_telefone": "+5510999999999",
    "data_criacao": "2018-03-18T00:51:22.000Z",
    "fixo": false,
    "confirmado": true
}

O objeto é um modelo JSON que retorna com o status da sua bina cadastrada.

Para realizar a chamada, é necessário que esta contenha os parâmetros solicitados abaixo na tabela Atributos. Ao final, a API fará o retorno.

Endpoint: https://voice-app.zenvia.com/bina

Atributos

id integer	ID do registro de Bina
numero_telefone string	Número do telefone que será binado
data_criacao datetime	Data e hora que foi criado o registro
fixo boolean	Se o número da bina se refere a um telefone fixo
confirmado boolean	Se está confirmado que o número de telefone da bina pertence a você

Buscar Bina

Definição

GET https://voice-api.zenvia.com/bina/{id}

Request

curl -X GET --header 'Content-Type: application/json' \
            --header 'Accept: application/json' \ 
            --header 'Access-Token: {{access-token}}' \
            'https://voice-api.zenvia.com/bina/1'

Caso deseje, após a contratação de uma bina você poderá realizar a busca do registro pelo seu ID.

Para buscar, é necessário o envio da chave da bina na URL da requisição seguido da autenticação Access Token no Header.

A chamada para obter os dados da consulta deve ser realizada utilizando um HTTP GET para o endereço de definição da API.

GET https://voice-api.zenvia.com/bina/{id}

Request

ID Obrigatório

ID da Bina para recuperar os dados

Response

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "Dados retornados com sucesso",
  "dados": {
    "id": 1,
    "numero_telefone": "+5510999999999",
    "data_criacao": "2018-03-18T00:51:22.000Z",
    "fixo": false,
    "confirmado": true
  }
}

dados object

Retorna o objeto Bina

Deletar Bina

Definição

DELETE https://voice-api.zenvia.com/bina/{id}

Request

curl -X DELETE --header 'Content-Type: application/json' \
            --header 'Accept: application/json' \ 
            --header 'Access-Token: {{access-token}}' \
            'https://voice-api.zenvia.com/bina/1'

Para deletar um número de telefone (Bina) cadastrado na sua conta, basta informar o ID da bina.

Importante: isso não cancela a contratação do número de telefone, para isso é necessário entrar em contato com a Zenvia. O método “delete” apenas impede que o número seja utilizado como bina. Porém, ele continua disponível para uso em outras features.

Método utilizado:

DELETE https://voice-api.zenvia.com/bina/{id}

Relatório Bina

Definição

GET https://voice-api.zenvia.com/bina/relatorio

Request

curl -X GET --header 'Content-Type: application/json' \
            --header 'Accept: application/json' \ 
            --header 'Access-Token: {{access-token}}' \
            'https://voice-api.zenvia.com/bina/relatorio'

Para buscar os telefones (Bina) cadastrados na Conta, basta realizar a chamada utilizando um HTTP GET para o endereço de definição da API.

GET https://voice-api.zenvia.com/bina/relatorio

Central Telefônica

Usando esse recurso, você poderá fazer configurações e retirar relatórios de ramal e URAs.

Objeto Ramal

JSON

{
    "id": 76498,
    "ramal": "3333",
    "login": "testee@zenvia.com",
    "bina": "+5510888888888",
    "webphone_key": "213kbbncs324454ASDcxzln123",
    "ligacao_externa": true,
    "ligacao_celular": true,
    "gravar_audio": true,
    "acesso_gravacoes": true,
    "webphone": false,
    "ura_id": null,
    "voicemail": false,
    "tags": ""
}

O objeto é um modelo JSON. Para realizar a chamada, é necessário que esta contenha os parâmetros solicitados abaixo na tabela Atributos.

Endpoint: https://voice-api.zenvia.com/ramal

Atributos

id integer	ID do ramal
ramal integer	Número do ramal
login string	E-mail de login do ramal
bina string	Número que aparece quando o ramal faz ligações
webphone_key string	Chave para utilização de webphones integrados
ligacao_externa boolean	Permite fazer ligações externas
ligacao_celular boolean	Permite fazer ligações para números de celular
gravar_audio boolean	Grava as ligações deste ramal

Criar ramal

Definição

POST https://voice-api.zenvia.com/ramal

Request

curl -X POST --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: seu-token' \
             -d '{"ramal":"","login":"","senha":""}' \
             'https://voice-api.zenvia.com/ramal'

<?php
require_once "vendor/autoload.php";
use TotalVoice\Client as TotalVoiceClient;

$client = new TotalVoiceClient('seu-token');
$dados = [
    "ramal"=>"1358",
    "login"=>"logindeteste231@totalvoice.com.br"
];
$response = $client->central->criarRamal($dados);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

const dados = {
    ramal: '1358', 
    login: 'logindeteste231@totalvoice.com.br', 
    senha: '123456'
};

client.central.criarRamal(dados)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
Em construção

client = Cliente("seu-token", 'voice-api.zenvia.com')
Em construção

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Em construção

require 'totalvoice-ruby'
include TotalVoice

Em construção

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "ramal criado com sucesso",
  "dados": {
    "id": 1234,
    "ramal": 4000,
    "login": "123teste231@zenvia.com",
    "senha": "123teste23122",
    "bina": null,
    "webphone_key": "123teste231224d549e0408e123teste23122",
    "ligacao_externa": false,
    "ligacao_celular": false,
    "gravar_audio": false,
    "acesso_gravacoes": false,
    "webphone": true,
    "ura_id": null,
    "voicemail": false,
    "tags": null
  }
}

Para criar um ramal nenhum campo é obrigatório, mas indicamos que você passe os parâmetros ramal e login para controlar melhor os ramais criados.

POST: https://voice-api.zenvia.com/chamada

REQUEST:

• Headers

1. Content-Type: application/json
2. Authorization: Access-Token: seu-token

Veja ao lado um exemplo de requisição. Utilize os campos abaixo para informar à nossa API as informações que irá enviar:

Request

ramal integer	Número do ramal
login string	E-mail de login do ramal
senha string	Senha do ramal. (Deve conter 8 caracteres, sendo pelo menos 1 maiúsculo e 1 minúsculo)
bina string	Número que aparece quando o ramal faz ligações
ligacao_externa boolean	Permite fazer ligações externas
ligacao_celular boolean	Permite fazer ligações para números de celular
gravar_audio boolean	Permite a gravação de áudio
acesso_gravacoes boolean	Permite o usuário deste ramal ver gravações
webphone boolean	Permite o usuário utilizar webphone
ura_id integer	Caso tenha um valor aqui ao telefonar para este número de ramal, vai cair em uma URA ao invés de chamar o usuário
voicemail boolean	Se esse valor for igual a true, ao ligar para esse ramal ele será encaminhado para uma caixa postal que gravará recados. (Não irá chamar no usuário)

Response

dados object

Retorna o objeto com os dados do ramal criado

Buscar Ramal

Definição

GET https://voice-api.zenvia.com/ramal/{id}

Request

curl -X GET --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: seu-token' \
             'https://voice-api.zenvia.com/ramal/{id}'

<?php

require_once "vendor/autoload.php";
use TotalVoice\Client as TotalVoiceClient;

$client = new TotalVoiceClient('seu-token');

$response = $client->central->buscaRamal("id-ramal");

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.central.buscaRamal('id-ramal')
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
Em construção

client = Cliente("seu-token", 'voice-api.zenvia.com')
Em construção

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Em construção

require 'totalvoice-ruby'
include TotalVoice

Em construção

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "id": 1234,
    "ramal": "4000",
    "login": "teste@zenvia.com",
    "bina": "+5510888888888",
    "webphone_key": "testefd3b268b3de8cateste44968",
    "ligacao_externa": true,
    "ligacao_celular": true,
    "gravar_audio": true,
    "acesso_gravacoes": true,
    "webphone": false,
    "ura_id": null,
    "voicemail": false,
    "tags": ""
  }
}

Para buscar um ramal e suas informações, basta informar o ID da mesma após o seu envio.

Método utilizado:

GET https://voice-api.zenvia.com/ramal/{id}

Request

id integer

ID do ramal

Response

dados object

Retorna o objeto do ramal

Editar Ramal

Definição

PUT https://voice-api.zenvia.com/ramal/{id}

Request

curl -X PUT --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: seu-token' \
             -d '{"senha":"4321789"}' \
             'https://voice-api.zenvia.com/ramal/{id}'

<?php
require_once "vendor/autoload.php";
use TotalVoice\Client as TotalVoiceClient;

$client = new TotalVoiceClient('seu-token');

$dados = [
    "ramal"=>"1358",
    "login"=>"logindeteste231@totalvoice.com.br"
];

$response = $client->central->atualizarRamal("id-ramal", $dados);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

const dados = {
    login: 'logindeteste456@totalvoice.com.br', 
    senha: '12345678'
};

client.central.atualizarRamal('id-ramal', dados)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
Em construção

client = Cliente("seu-token", 'voice-api.zenvia.com')
Em construção

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Em construção

require 'totalvoice-ruby'
include TotalVoice

Em construção

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados atualizados com sucesso",
  "dados": null
}

Para alterar as informações do ramal, o método de solicitação deve ser HTTP PUT. Ele criará um novo recurso e substituirá as antigas informações.

PUT https://voice-api.zenvia.com/ramal/{id}

Request

id integer	Id do ramal que será modificado(O id é passado na URL do endpoint)
ramal integer	Número do ramal
login string	E-mail de login do ramal
senha string	Senha do ramal (Deve conter 8 caracteres, sendo pelo menos 1 maiúsculo e 1 minúsculo)
bina string	Número que aparece quando o ramal faz ligações
ligacao_externa boolean	Permite fazer ligações externas
ligacao_celular boolean	Permite fazer ligações para números de celular
gravar_audio boolean	Permite a gravação de áudio
acesso_gravacoes boolean	Permite o usuário deste ramal ver gravações
webphone boolean	Permite o usuário utilizar webphone
ura_id integer	Caso tenha um valor aqui, ao telefonar para este número de ramal, vai cair em uma URA ao invés de chamar o usuário. Caso queira desvincular uma URA basta passar o valor 'null' neste campo.
voicemail boolean	Se esse valor for igual a true, ao ligar para esse ramal ele será encaminhado para uma caixa postal que gravará recados.(Não irá chamar no usuário)

Response

status object

Retorna o status da requisição

Editar Ramal na fila

Definição

PUT https://voice-api.zenvia.com/ramal/{id}/fila

Request

curl -X PUT --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: seu-token' \
             -d '{"status_pausa":true, "fila":41}' \
             'https://voice-api.zenvia.com/ramal/{id}/fila'

<?php
require_once "vendor/autoload.php";
use TotalVoice\Client as TotalVoiceClient;

$client = new TotalVoiceClient('seu-token');

$dados = [
    "status_pausa"=>true,
    "fila"=>41
];

$response = $client->central->atualizarRamalFila("id-ramal", $dados);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.central.atualizarRamalFila(ramal_id, data)

client := totalvoice.NewTotalVoiceClient("seu-token")
response, err := client.RamalFila.Atualizar(ramal_id, data)

client = Cliente("seu-token", 'voice-api.zenvia.com')
client.ramal.editarRamalFila(ramal_id, data)

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Central central = new Central(client);
JSONObject response = central.atualizarRamalFila(ramal_id, data);

@client = TotalVoice::API.new("9754aac7641722789c80c237f9afb4b1", "voice-api.zenvia.com")
puts @client.ramal.atualizar_ramal_fila(ramal_id, data)

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "Ramal pausado com sucesso na fila 41",
  "dados": [
    {
      "ramal_id": 16,
      "pausado": true,
      "fila": 41
    }
  ]
}

Para alterar as informações de um ramal na fila, o método de solicitação também deve ser HTTP PUT. Ele criará um novo recurso e substituirá as antigas informações.

Lembre-se apenas que o ID informado na URL do endpoint é aquele que será modificado.

PUT https://voice-api.zenvia.com/ramal/{id}

Request

id integer	Id do ramal que será modificado(O id é passado na URL do endpoint)
status_pausa boolean	Pausa (true) ou despausa (false)
fila integer	Id da fila que você quer pausar o ramal

Response

status object

Retorna o status da requisição

Deletar Ramal

Definição

DELETE https://voice-api.zenvia.com/ramal/{id}

Request

curl -X DELETE --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: seu-token' \
             'https://voice-api.zenvia.com/ramal/{id}'

<?php
require_once "vendor/autoload.php";
use TotalVoice\Client as TotalVoiceClient;

$client = new TotalVoiceClient('seu-token');

$response = $client->central->excluirRamal("id-ramal");

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.central.excluirRamal('id-ramal')
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
Em construção

client = Cliente("seu-token", 'voice-api.zenvia.com')
Em construção

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Em construção

require 'totalvoice-ruby'
include TotalVoice

Em construção

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "Ramal Removido",
  "dados": null
}

Para deletar um ramal, basta informar o ID do mesmo.

Método utilizado:

DELETE https://voice-api.zenvia.com/ramal/{id}

Request

id integer

ID do ramal

Response

dados object

Retorna o status da requisição

Listar Ramais criados

Definição

GET https://voice-api.zenvia.com/ramal/relatorio

Request

curl -X GET --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' \
            'https://voice-api.zenvia.com/ramal/relatorio?data_inicio=2018-03-14&data_fim=2018-03-15'

<?php
$client = new TotalVoiceClient('seu-token');
Em construção

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.central.relatorio()
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
Em construção

client = Cliente("seu-token", 'voice-api.zenvia.com')
Em construção

Em construção

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "relatorio": [
      {
        "id": 1234,
        "ramal": "4000",
        "login": "teste@totalTeste.com.br",
        "bina": "+5510888888888",
        "webphone_key": "totalTesteb8af64668997totalTeste",
        "ligacao_externa": true,
        "ligacao_celular": true,
        "gravar_audio": true,
        "acesso_gravacoes": false,
        "webphone": true,
        "ura_id": null,
        "voicemail": false,
        "tags": ""
      },
      {
        "id": 4567,
        "ramal": "4001",
        "login": "teste1@totalTeste.com.br",
        "bina": "+5510888888888",
        "webphone_key": "teste18e990a500a059a78teste1",
        "ligacao_externa": true,
        "ligacao_celular": true,
        "gravar_audio": true,
        "acesso_gravacoes": true,
        "webphone": true,
        "ura_id": null,
        "voicemail": false,
        "tags": ""
      }
    ]
  }
}

Para listar os ramais criados, basta informar a data de início e fim que deseja buscar.

Método utilizado:

GET https://voice-api.zenvia.com/ramal/relatorio

Request

data_inicio Obrigatório Query String	Data inicial para consulta dos dados no relatório
data_fim Obrigatório Query String	Data final para consulta dos dados no relatório
posicao Opcional Query String	Posição para seleção dos dados do relatório - começa na posição 0. Também chamado de offset.
limite Opcional Query String	Quantidade de chamadas a retornar na consulta. O limite padrão é 100 e o máximo é 200.

Response

relatorio array

Retorna um array com objetos ramal

Listar pausas do ramal

Definição

GET https://voice-api.zenvia.com/ramal/{id}/pausas

Request

curl -X GET --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' \
            'https://voice-api.zenvia.com/ramal/{id}/pausas?data_inicio=2018-03-14&data_fim=2018-03-15'

<?php
require_once "vendor/autoload.php";
use TotalVoice\Client as TotalVoiceClient;

$client = new TotalVoiceClient('seu-token');

$response = $client->central->relatorioPausasRamal("id-ramal", "2019-02-20T11:11:19-03:00", "2019-02-20T11:12:26-03:0");

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.central.relatorioPausas('id-ramal')
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
Em construção

client = Cliente("seu-token", 'voice-api.zenvia.com')
Em construção

Em construção

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "total": 1,
    "duracao_total": "00:00:07",
    "duracao_total_segundos": 7,
    "ramal": "4000",
    "posicao": 0,
    "limite": 100,
    "relatorio": [
      {
        "pausa_inicio": "2019-06-15T11:14:41-03:00",
        "pausa_fim": "2019-06-15T11:14:48-03:00",
        "tempo_segundos": 7,
        "tempo": "00:00:07"
      }
    ]
  }
}

Para listar as pausas dos ramais criados, basta informar o ID do ramal, a data de início e fim que deseja buscar.

Método utilizado:

GET https://voice-api.zenvia.com/ramal/{id}/pausas

Request

id Obrigatório integer	Id do ramal que será modificado(O id é passado na URL do endpoint)
data_inicio Obrigatório Query String	Data inicial para consulta dos dados no relatório
data_fim Obrigatório Query String	Data final para consulta dos dados no relatório
posicao Opcional Query String	Posição para seleção dos dados do relatório - começa na posição 0. Também chamado de offset.
limite Opcional Query String	Quantidade de chamadas a retornar na consulta. O limite padrão é 100 e o máximo é 200.

Response

dados object

Retorna o objeto com os dados de pausa do ramal

Listar ligações do ramal

Definição

Lista as ligações recebidas por um ramal no período desejado.

GET https://voice-api.zenvia.com/ramal/{id}/relatorio

Request

curl -X GET --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' \
            'https://voice-api.zenvia.com/ramal/{id}/relatorio?data_inicio=2018-03-14&data_fim=2018-03-15'

<?php
$client = new TotalVoiceClient('seu-token');
Em construção

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.central.relatorio('id-ramal')
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
Em construção

client = Cliente("seu-token", 'voice-api.zenvia.com')
Em construção

Em construção

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "total": 2,
    "posicao": 0,
    "limite": 100,
    "relatorio": [
      {
        "id": 123456,
        "data_inicio": "2019-05-07T15:28:13-03:00",
        "url_gravacao": "https://api.evoline.com.br/rec/?id=123445&x=12345&cid=1",
        "numero_origem": "+5510999999999",
        "status": "atendida",
        "duracao_segundos": 369,
        "duracao": "00:06:09",
        "preco": "0.00",
        "ramal": {
          "id": 60679,
          "ramal": "4000",
          "login": "teste@totaltestevoice.com.br"
        }
      },
      {
        "id": 123456,
        "data_inicio": "2019-05-08T13:16:02-03:00",
        "url_gravacao": "https://api.evoline.com.br/rec/?id=123456&x=12345&cid=1",
        "numero_origem": "+5510999999999",
        "status": "atendida",
        "duracao_segundos": 596,
        "duracao": "00:09:56",
        "preco": "0.00",
        "ramal": {
          "id": 1234,
          "ramal": "4000",
          "login": "teste@totaltestevoice.com.br"
        }
      }
    ]
  }
}

Para listar as ligações recebidas por um ramal, basta informar o ID do ramal, a data de início e fim que deseja buscar.

Método utilizado:

GET https://voice-api.zenvia.com/ramal/{id}/relatorio

Request

id Obrigatório integer	Id do ramal que será modificado(O id é passado na URL do endpoint)
data_inicio Obrigatório Query String	Data inicial para consulta dos dados no relatório
data_fim Obrigatório Query String	Data final para consulta dos dados no relatório
posicao Opcional Query String	Posição para seleção dos dados do relatório - começa na posição 0. Também chamado de offset.
limite Opcional Query String	Quantidade de chamadas a retornar na consulta. O limite padrão é 100 e o máximo é 200.

Response

relatorio array

Retorna um array com objetos de chamadas atendidas

Fila

Fila Endpoint

https://voice-api.zenvia.com/fila

Usando esse recurso, será possível automatizar e manipular as filas de atendimento.

Nossa API oferece a solução para o gerenciamento de filas de espera, desde a chegada do cliente até a conclusão, auxiliando empresas a ressaltar a qualidade do atendimento.

Será viável também:

• Monitorar o tempo de espera;
• Obter informações detalhadas como tempo médio de espera, atendimento e qualidade.

Objeto Fila

JSON

{
    "id": 432,
    "nome": "Suporte",
    "chamadas": 0,
    "completado": 0,
    "cancelado": 0,
    "tempo_falado": "00:00:00",
    "tempo_espera": "00:00:00",
    "ramais": [
      {
         "id": 17,
         "nome": "Teste Atendimento",
         "ramal": "4000",
         "login": "ramal@empresa.com.br",
         "prioridade": "0",
         "qtd_ligacao_atendida": "0",
         "ultima_chamada": "0",
         "em_ligacao": false,
         "status": "indisponivel",
         "em_pausa": false,
         "razao_pausa": "",
         "bina": null,
         "tempo_status": "04:38:36"     
      }
    ]
}

O objeto é um modelo JSON que retorna as filas cadastradas em sua conta.

Para realizar a chamada, é necessário que esta contenha os parâmetros solicitados abaixo na tabela Atributos. Ao final, a API fará o retorno.

Endpoint: https://voice-api.zenvia.com/fila

Atributos

id integer	ID do registro da Fila.
nome string	Nome da fila.
chamadas integer	Número de chamadas da fila.
completado integer	Número de chamadas completadas.
cancelado integer	Número de chamadas canceladas.
tempo_falado string	Total de tempo falado da fila.
tempo_espera string	Total de tempo de ramais em espera na fila.
ramais array	Lista de ramais pertencentes a fila

Criar Fila

Definição

POST https://voice-api.zenvia.com/fila

Request

curl -X POST --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: {{access-token}}' \
             -d '{"nome":"Suporte","estrategia_ring":"Multiplo", "timeout_ring": "60"}' \
             'https://voice-api.zenvia.com/fila'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->fila->criar('Suporte', 'Multiplo', '60');

const totalvoice = require('totalvoice-node');
const client = new totalvoice("testeM68PU1Izmb9chEdLzep7IwRymWO");

client.fila.enviar("Suporte", "Multiplo", "60")
    .then(function(data) {  
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.Fila.Criar("Suporte", "Multiplo", 60)

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.fila.criar("Suporte", "Multiplo", "60")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Fila fila = new Fila(client);

JSONObject response = fila.enviar("Suporte", "Multiplo")

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.fila.criar("Suporte", "Multiplo", "60")

Response

{
    "status": 200,
    "sucesso": true,
    "motivo": 0,
    "mensagem": "fila criada com sucesso",
    "dados": {
        "id": 4921
    }
}

Para criar uma fila, basta informar o nome da mesma e a estratégia de ring, que pode ser de três tipos:

• Múltiplo;
• Distribuidor;
• Distribuidor/Paralelo.

POST: https://voice-api.zenvia.com/fila

REQUEST:

• Headers

1. Content-Type: application/json
2. Authorization: Access-Token: {{access-token}}

Request

nome Obrigatório	Nome da fila a ser criada.
estrategia_ring Obrigatório	Distribuidor = Toca um ramal por vez, DistribuidorParalelo = Toca um ramal por vez com encaminhamento paralelo ou Multiplo = Toca todos ramais ao mesmo tempo.
timeout_ring Opcional	Segundos que vai ficar tocando na fila

Response

id integer

Retorna o ID da Fila

Buscar Fila

Definição

GET https://voice-api.zenvia.com/fila/{id}

Request

curl -X GET --header 'Content-Type: application/json' \
            --header 'Accept: application/json' \
            --header 'Access-Token: {{access-token}}' 'https://voice-api.zenvia.com/fila/1'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->fila->buscar(123);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("testeM68PU1Izmb9chEdLzep7IwRymWO");

client.fila.buscar(123)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.Fila.Buscar(123)

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.fila.get_fila(123)

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Fila fila = new Fila(client);

JSONObject response = fila.buscar(123);

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("{{access-token}}")
puts @client.fila.buscar(123)

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "id": 1,
    "nome": "Suporte",
    "chamadas": 0,
    "completado": 0,
    "cancelado": 0,
    "tempo_falado": "00:00:00",
    "tempo_espera": "00:00:00",
    "ramais": [
      {
        "id": 17,
        "nome": "Teste Atendimento",
        "ramal": "4000",
        "login": "ramal@empresa.com.br",
        "prioridade": "0",
        "qtd_ligacao_atendida": "0",
        "ultima_chamada": "0",
        "em_ligacao": false,
        "status": "indisponivel",
        "em_pausa": false,
        "razao_pausa": "",
        "bina": null,
        "tempo_status": "04:38:36"
      }
    ]
  }
}

Caso deseje, após a criação de uma fila você poderá realizar a busca do registro pelo seu ID.

Para buscar, é necessário o envio da chave da fila na URL da requisição seguido da autenticação Acess Token no Header.

A chamada para obter os dados da consulta deve ser realizada utilizando um HTTP GET para o endereço de definição da API.

GET https://voice-api.zenvia.com/fila/{id}

Request

ID Obrigatório

ID da Fila para recuperar os dados

Response

dados object

Retorna o objeto fila

Editar Fila

Definição

PUT https://voice-api.zenvia.com/fila/{id}

Request

curl 'https://voice-api.zenvia.com/fila/1' \
    -X PUT \
    --header 'Content-Type: application/json' \
    --header 'Access-Token: testeM68PU1Izmb9chEdLzep7IwRymWO' \
    -d '{"nome":"Suporte","estrategia_ring":"Multiplo", "timeout_ring": "60"}'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->fila->atualizarFila("Suporte", "Multiplo", "60");

const totalvoice = require('totalvoice-node');
const client = new totalvoice("testeM68PU1Izmb9chEdLzep7IwRymWO");

client.fila.atualizarFila("Suporte", "Multiplo", "60")
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.Fila.Atualizar("Suporte", "Multiplo", "60")

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.fila.editar("Suporte", "Multiplo", "60")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Fila fila = new Fila(client);

JSONObject response = fila.atualizar("Suporte", "Multiplo");

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("{{access-token}}")
puts @client.fila.atualizar("Suporte", "Multiplo", "60")

Response

{
    "status": 200,
    "sucesso": true,
    "motivo": 0,
    "mensagem": "dados atualizados com sucesso",
    "dados": null
}

Para alterar as informações da sua fila, o método de solicitação deve ser HTTP PUT. Ele criará um novo recurso e substituirá as antigas informações.

PUT https://voice-api.zenvia.com/fila/{id}

Request

nome Opcional	Novo nome da fila.
estrategia_ring Opcional	Distribuidor = Toca um ramal por vez, DistribuidorParalelo = Toca um ramal por vez com encaminhamento paralelo ou Multiplo = Toca todos ramais ao mesmo tempo.
timeout_ring Opcional	Segundos que vai ficar tocando na fila

Response

Retorna o objeto resposta padrão da API com sucesso ou falha.

Adicionar ramal

Definição

POST https://voice-api.zenvia.com/fila/{id}

Request

curl -X POST --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: {{access-token}}' \
             -d '{"ramal_id":"111"}' \
             'https://voice-api.zenvia.com/fila/123'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->fila->addRamal("ID_FILA", "RAMAL_ID");

const totalvoice = require('totalvoice-node');
const client = new totalvoice("testeM68PU1Izmb9chEdLzep7IwRymWO");

client.fila.addRamal("ID_FILA", "RAMAL_ID")
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.Fila.AdicionarRamalFila("ID_FILA", "RAMAL_ID");

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.fila.add_ramal("ID_FILA", "RAMAL_ID")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Fila fila = new Fila(client);

JSONObject response = fila.adicionaRamalFila("ID_FILA", "RAMAL_ID");

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.fila.adiciona_ramal("ID_FILA", "RAMAL_ID")

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "Ramal adicionado com sucesso na fila",
  "dados": {
    "id": 4921
  }
}

Para adicionar um ramal na fila, basta informar o ID da mesma e, por parâmetro, o ID do ramal que deseja adicionar.

Método utilizado:

POST https://voice-api.zenvia.com/fila/{id}

Deletar ramal

Definição

DELETE https://voice-api.zenvia.com/fila/{id}

Request

curl -X DELETE --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: {{access-token}}' \
            'https://voice-api.zenvia.com/fila/111/111'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->fila->excluirRamalFila("ID_FILA", "RAMAL_ID");

const totalvoice = require('totalvoice-node');
const client = new totalvoice("testeM68PU1Izmb9chEdLzep7IwRymWO");

client.fila.excluirRamalFila("ID_FILA", "RAMAL_ID")
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.Fila.ExcluirRamalFila("ID_FILA", "RAMAL_ID")

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.fila.deleta_ramal("ID_FILA", "RAMAL_ID")

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.fila.excluir_ramal("ID_FILA", "RAMAL_ID")

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "Ramal removido da fila com sucesso"
}

Para deletar um ramal na fila, basta informar o ID da mesma e, por parâmetro, o ID do ramal que deseja remover.

Método utilizado:

DELETE https://voice-api.zenvia.com/fila/{id}

Buscar ramal

Definição

GET https://voice-api.zenvia.com/fila/{id-fila}/{id-ramal}

Request

curl -X GET --header 'Content-Type: application/json' \
            --header 'Accept: application/json' \
            --header 'Access-Token: {{access-token}}' 'https://voice-api.zenvia.com/fila/id-fila/id-ramal'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->fila->buscarFilaRamal("ID_FILA", "RAMAL_ID")

const totalvoice = require('totalvoice-node');
const client = new totalvoice("testeM68PU1Izmb9chEdLzep7IwRymWO");

client.fila.buscarRamalFila("ID_FILA", "RAMAL_ID")
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.Fila.BuscarRamalFila("ID_FILA", "RAMAL_ID")

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.fila.get_fila_ramal("ID_FILA", "RAMAL_ID")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Fila fila = new Fila(client);

JSONObject response = fila.buscar("ID_FILA", "RAMAL_ID");

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.fila.buscar_ramal("ID_FILA", "RAMAL_ID")

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "id": 1,
    "nome": "Suporte",
    "chamadas": 0,
    "completado": 0,
    "cancelado": 0,
    "tempo_falado": "00:00:00",
    "tempo_espera": "00:00:00",
    "ramais": [
      {
        "id": 17,
        "nome": "Teste Atendimento",
        "ramal": "4000",
        "login": "ramal@empresa.com.br",
        "prioridade": "0",
        "qtd_ligacao_atendida": "0",
        "ultima_chamada": "0",
        "em_ligacao": false,
        "status": "indisponivel",
        "em_pausa": false,
        "razao_pausa": "",
        "bina": null,
        "tempo_status": "04:38:36"
      }
    ]
  }
}

Para buscar um ramal na fila, basta informar o ID da mesma e, por parâmetro, o ID do ramal que deseja buscar.

Método utilizado:

GET https://voice-api.zenvia.com/fila/{id-fila}/{id-ramal}

Relatório Fila

Definição

GET https://voice-api.zenvia.com/fila/{id}/relatorio

Request

curl -X GET --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' \
            'https://voice-api.zenvia.com/fila/{id-fial}/relatorio?data_inicio=2018-03-14&data_fim=2018-03-15'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->fila->relatorioChamadas($id_fila,$dataInicial, $dataFinal);

Em construção

Em construção

Em construção

Em construção

Em construção

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "total": 8,
    "posicao": 0,
    "limite": 100,
    "relatorio": [
      {
        "id": 1324567,
        "numero_destino": "+5510999999999",
        "numero_origem": "+5510999999999",
        "data_inicio": "2019-07-15T08:32:34.000-03:00",
        "status": "Não atendida",
        "atendida": false,
        "ativa": 0,
        "duracao_segundos": 237,
        "duracao": "00:03:57",
        "duracao_cobrada_segundos": 0,
        "duracao_cobrada": "00:00:00",
        "duracao_falada_segundos": 0,
        "duracao_falada": "00:00:00",
        "tempo_espera": 225,
        "preco": 0,
        "url_gravacao": "https://api.evoline.com.br/rec/?id=123sd213",
        "fila": {
          "id": 430,
          "data_inicio": "2019-07-15T08:31:47.000-03:00"
        },
        "ramal": {}
      },
      {
        "id": 43211234,
        "numero_destino": "+5510999999999",
        "numero_origem": "+5510999999999",
        "data_inicio": "2019-07-15T09:02:47.000-03:00",
        "status": "Atendida",
        "atendida": true,
        "ativa": 0,
        "duracao_segundos": 296,
        "duracao": "00:04:56",
        "duracao_cobrada_segundos": 286,
        "duracao_cobrada": "00:04:46",
        "duracao_falada_segundos": null,
        "duracao_falada": null,
        "tempo_espera": null,
        "preco": 0,
        "url_gravacao": "https://api.evoline.com.br/rec/?id=691325",
        "fila": {
          "id": 430,
          "data_inicio": "2019-07-15T09:02:47.000-03:00"
        },
        "ramal": {
          "id": 12342454,
          "ramal": "4099",
          "login": "suporte.voz@zenvia.com"
        }
      }
    ]
  }
}

Para consultar os áudios das chamadas de uma fila, basta informar o período desejado para que a API retorne os dados.

Veja ao lado um exemplo de requisição. Os campos são:

Request

id Obrigatório Query String	Id da fila que deseja consultar as ligações
data_inicio Obrigatório Query String	Data inicial para consulta dos dados no relatório
data_fim Obrigatório Query String	Data final para consulta dos dados no relatório
origem Opcional Query String	Número de origem da ligação recebida
destino Opcional Query String	Número de destino da ligação recebida
posicao Opcional Query String	Posição para seleção dos dados do relatório - começa na posição 0. Também chamado de offset.
limite Opcional Query String	Quantidade de chamadas a retornar na consulta. O limite padrão é 100 e o máximo é 200.

Response

relatorio array

Retorna um array com objetos chamadas recebidas

Números de telefone (DID)

DID são mais conhecidos como “números virtuais” e possibilitam receber chamadas utilizando a conexão com a internet.

Usando esse recurso, será possível automatizar o gerenciamento de números de telefone por meio das funcionalidades:

• Gerenciar, adquirir ou remover um DID da sua Conta.
• Extrair relatórios dos DIDs adquiridos e das chamadas recebidas por um número específico da sua conta.

Objeto DID

Did Endpoint

https://voice-api.zenvia.com/did

JSON

    {
    "id": 4844577,
    "cidade": "Rio de Janeiro",
    "estado": "RJ",
    "numero": "+5510999999999"
    }

O objeto é um modelo JSON. Para realizar a chamada, é necessário que esta contenha os parâmetros solicitados abaixo na tabela Atributos.

Endpoint: https://voice-api.zenvia.com/did

Atributos

id integer	ID do DID(Número receptivo)
cidade string	Cidade do número de telefone(DID)
estado string	Estado/Região do DID
numero datetime	Número completo do DID

Consultar DIDs

Did Endpoint

https://voice-api.zenvia.com/did

Request

curl -X GET --header 'Content-Type: application/json' \
            --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' 'https://voice-api.zenvia.com/did'

<?php
require_once "vendor/autoload.php";
use TotalVoice\Client as TotalVoiceClient;

$client = new TotalVoiceClient('seu-token');

$response = $client->central->listaEstoque("id-ramal");

Em construção

Em construção

Em construção

Em construção

Em construção

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "dids": [
      {
        "id": 123454,
        "cidade": "Rio de Janeiro",
        "estado": "RJ",
        "numero": "+5510999999999"
      }
    ]
  }
}

Você poderá realizar a consulta da lista de todos os DIDs da sua conta.

Para requisitar, não é necessário passar nenhum parâmetro. Basta realizar a chamada para obter os dados utilizando um HTTP GET para o endereço de definição da API.

GET https://voice-api.zenvia.com/did

Atualizar DID

Definição

PUT https://voice-api.zenvia.com/did/{id}

Request

curl -X PUT --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: seu-token' \
             -d '{"ura_id":"4321789"}' \
             'https://voice-api.zenvia.com/did/{id}'

<?php
require_once "vendor/autoload.php";
use TotalVoice\Client as TotalVoiceClient;

Em construção

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

Em construção

client := totalvoice.NewTotalVoiceClient("seu-token")
Em construção

client = Cliente("seu-token", 'voice-api.zenvia.com')
Em construção

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Em construção

require 'totalvoice-ruby'
include TotalVoice

Em construção

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados atualizados com sucesso",
  "dados": null
}

Para atualizar os dados de um DID, o método de solicitação deve ser HTTP PUT. Ele criará um novo recurso e substituirá as antigas informações.

PUT https://voice-api.zenvia.com/did/{id}

Request

id integer	Id do ramal que será modificado(O id é passado na URL do endpoint)
ura_id integer	ID da URA, a qual irá atender a ligação no momento em que o número receber uma ligação.¹
ramal_id integer	ID do ramal, o qual irá atender a ligação no momento em que o número receber uma ligação.¹

Response

status object

Retorna o status da requisição

Deletar DID

Para deletar um número de telefone (DID) cadastrado na sua conta, basta informar o ID do mesmo.

Método utilizado:

DELETE https://voice-api.zenvia.com/did/{id}

Objeto Chamada DID

Chamada Recebidas Endpoint

https://voice-api.zenvia.com/did/chamada/{id}

JSON

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "id": 21344543,
    "ativa": false,
    "url_gravacao": "https://api.evoline.com.br/rec/sua-gravacao.mp3",
    "data_inicio": "2019-07-10T09:45:49-03:00",
    "numero_destino": "+5510999999999",
    "numero_origem": "+5510999999999",
    "status": "sem resposta",
    "duracao_segundos": 18,
    "tags": null,
    "duracao": "00:00:18",
    "duracao_cobrada_segundos": 0,
    "duracao_cobrada": "00:00:00",
    "duracao_falada_segundos": 0,
    "duracao_falada": "00:00:00",
    "preco": 0,
    "ramal_id": 34484,
    "ramal": "2000",
    "gravacoes_parciais": []
  }
}

O objeto é um modelo JSON. Para realizar a chamada, é necessário que esta contenha os parâmetros solicitados abaixo na tabela Atributos.

Endpoint: https://voice-api.zenvia.com/did/chamada/{id}

Atributos

id integer	ID do registro da chamada.
ativa boolean	Identifica se a chamada está ativa ou não
url_gravacao string	URL com áudio da gravação da chamada
data_inicio datetime	Data de início do registro da chamada. Data e Hora no formato UTC
numero_destino string	Número de destino da ligação
numero_origem string	Número que originou a ligação.
status string	Status da ligação na Origem/Destino: atendida sem resposta ocupado congestionado falha cancelada não existe
duracao_segundos integer	Duração em segundos (inteiro) do total da chamada desde o início do processamento
duracao integer	Duração total da chamada desde o início do processamento
duracao_cobrada_segundos integer	Duração em segundos para fins de cobrança
duracao_cobrada integer	Duração considerada para fins de cobrança
duracao_falada_segundos integer	Duração em segundos da chamada desde que o destino atendeu
duracao_falada integer	Duração da chamada desde que o destino atendeu
preco float	Valor cobrado pela chamada
ramal_id integer	ID do ramal vinculado ao DID

Buscar chamada recebida

Definição

GET https://voice-api.zenvia.com/did/chamada/{id-chamada}

Request

curl -X GET --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' \
            'https://voice-api.zenvia.com/did/chamada/{id-chamada}'

Em Construção

Em Construção

Em Construção

Em Construção

Em Construção

Em Construção

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "total": 3,
    "posicao": 0,
    "limite": "100",
    "relatorio": [
      {
        "id": 1,
        "ativa": false,
        "url_gravacao": "https://url-gravacao/rec/?id=1",
        "data_inicio": "2018-09-27T16:35:15-03:00",
        "numero_destino": "+5510999999999",
        "numero_origem": "+5510999999999",
        "status": "ocupado",
        "duracao_segundos": 15,
        "duracao": "00:00:15",
        "duracao_cobrada_segundos": 0,
        "duracao_cobrada": "00:00:00",
        "duracao_falada_segundos": 0,
        "duracao_falada": "00:00:00",
        "preco": 0,
        "ramal_id": 1231313
      }
    ]
  }
}

Você poderá consultar as chamadas recebidas por um DID.

Para requisitar, basta informar o período desejado e o ID do DID para que a API retorne os dados.

GET https://voice-api.zenvia.com/did/chamada/{id-chamada}

Request

id Obrigatório

ID da chamada recebida a ser consultada

Response

dados object

Dados da chamada recebida.

Relatório chamadas recebidas por DID

Definição

GET https://voice-api.zenvia.com/did/{id}/relatorio

Request

curl -X GET --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' \
            'https://voice-api.zenvia.com/did/1/relatorio?data_inicio=2018-03-14&data_fim=2018-03-15'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->did->relatorioChamadas($id, $dataInicial, $dataFinal, $filtros);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.did.relatorioChamadas(id, dataInicial, dataFinal, filtros)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
response, err := client.DID.RelatorioChamadas.Gerar(id, dataInicial, dataFinal, filtros)

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.did.get_relatorio_chamadas(id, data_inicio, data_fim, filtros)

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Did did = new Did(client);
JSONObject response = did.relatorioChamadas(id, dataInicial, dataFinal, filtros);

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.did.relatorioChamadas(id, data_inicial, data_final, filtros)

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "total": 3,
    "posicao": 0,
    "limite": "100",
    "relatorio": [
      {
        "id": 1,
        "ativa": false,
        "url_gravacao": "https://url-gravacao/rec/?id=1",
        "data_inicio": "2018-09-27T16:35:15-03:00",
        "numero_destino": "+5510999999999",
        "numero_origem": "+5510999999999",
        "status": "ocupado",
        "duracao_segundos": 15,
        "duracao": "00:00:15",
        "duracao_cobrada_segundos": 0,
        "duracao_cobrada": "00:00:00",
        "duracao_falada_segundos": 0,
        "duracao_falada": "00:00:00",
        "preco": 0,
        "ramal_id": 1231313
      }
    ]
  }
}

Para consultar as chamadas recebidas por um DID, basta informar o período desejado e o ID do DID para que a API retorne os dados.

Veja ao lado um exemplo de requisição. Os campos são:

Request

id Obrigatório	ID do DID que será consultado
data_inicio Obrigatório Query String	Data inicial para consulta dos dados no relatório
data_fim Obrigatório Query String	Data final para consulta dos dados no relatório
origem Opcional Query String	Número de telefone de origem para filtrar. Formato E.164: [+][DDI][DDD][Número]. Ex.: +5510999999999
destino Opcional Query String	Número de telefone de destino para filtrar. Formato E.164: [+][DDI][DDD][Número]. Ex.: +5510999999999
posicao Opcional Query String	Posição para seleção dos dados do relatório - começa na posição 0. Também chamado de offset.
limite Opcional Query String	Quantidade de chamadas a retornar na consulta. O limite padrão é 100 e o máximo é 200.

Response

total integer	Retorna a quantidade total de registros
posicao integer	Posição para seleção dos dados do relatório - começa na posição 0. Também chamado de offset.
limite integer	Quantidade de chamadas que retornou na consulta.
relatorio array	Retorna um array com objetos chamada DID

Relatório de todas as chamadas

Definição

GET https://voice-api.zenvia.com/did/relatorio

Request

curl -X GET --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' \
            'https://voice-api.zenvia.com/did/relatorio?data_inicio=2018-03-14&data_fim=2018-03-15'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->did->relatorioChamadas($dataInicial, $dataFinal, $filtros);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.did.relatorioChamadas(dataInicial, dataFinal, filtros)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
response, err := client.DID.RelatorioChamadas.Gerar(dataInicial, dataFinal, filtros)

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.did.get_relatorio_chamadas(data_inicio, data_fim, filtros)

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Did did = new Did(client);
JSONObject response = did.relatorioChamadas(dataInicial, dataFinal, filtros);

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.did.relatorioChamadas(data_inicial, data_final, filtros)

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "total": 3,
    "posicao": 0,
    "limite": "100",
    "relatorio": [
      {
        "id": 1,
        "ativa": false,
        "url_gravacao": "https://url-gravacao/rec/?id=1",
        "data_inicio": "2018-09-27T16:35:15-03:00",
        "numero_destino": "+5510999999999",
        "numero_origem": "+5510999999999",
        "status": "ocupado",
        "duracao_segundos": 15,
        "duracao": "00:00:15",
        "duracao_cobrada_segundos": 0,
        "duracao_cobrada": "00:00:00",
        "duracao_falada_segundos": 0,
        "duracao_falada": "00:00:00",
        "preco": 0,
        "ramal_id": 1231313
      }
    ]
  }
}

Para consultar todas as chamadas recebidas por todos os DIDs, basta informar o período desejado e o ID do DID para que a API retorne os dados.

Veja ao lado um exemplo de requisição. Os campos são:

Request

data_inicio Obrigatório Query String	Data inicial para consulta dos dados no relatório
data_fim Obrigatório Query String	Data final para consulta dos dados no relatório
origem Opcional Query String	Número de telefone de origem para filtrar. Formato E.164: [+][DDI][DDD][Número]. Ex.: +5510999999999
destino Opcional Query String	Número de telefone de destino para filtrar. Formato E.164: [+][DDI][DDD][Número]. Ex.: +5510999999999
posicao Opcional Query String	Posição para seleção dos dados do relatório - começa na posição 0. Também chamado de offset.
limite Opcional Query String	Quantidade de chamadas a retornar na consulta. O limite padrão é 100 e o máximo é 200.

Response

total integer	Retorna a quantidade total de registros
posicao integer	Posição para seleção dos dados do relatório - começa na posição 0. Também chamado de offset.
limite integer	Quantidade de chamadas que retornou na consulta.
relatorio array	Retorna um array com objetos chamada DID

URA

Usando esse recurso, será possível otimizar e automatizar suas chamadas com URAs (Unidade de Resposta Audível).

Uma URA possui uma estrutura de atendimento e, em nossa API, você tem diversas possibilidades.

Objeto URA

JSON

{
    "id": 78910,
    "nome": "Exemplo de URA",
    "dados": [
        {
            "timeout": 6,
            "menu": "menu 1",
            "opcao": "",
            "acao": "tts",
            "acao_dados": {
                "mensagem": "Voce ligou para Zenvia. Aperte 1 para ser atendido."
            }
        },
        {
            "timeout_fila": 600,
            "menu": "menu 1",
            "opcao": "1",
            "acao": "fila",
            "acao_dados": {
                "fila_id": "1234"
            }
        },
        {
            "timeout": 2,
            "menu": "menu 8",
            "opcao": "8",
            "acao": "digiteramal",
            "acao_dados": {
                "mensagem": "Digite o ramal desejado"
            }
        }
    ]
}

O objeto é um modelo JSON. Para realizar a chamada, é necessário que esta contenha os parâmetros solicitados abaixo na tabela Atributos. Ao final, a API fará o retorno.

Endpoint: https://voice-api.zenvia.com/ura

Atributos

id integer	ID da URA
nome string	Nome da URA
dados string	Dentro de dados você consegue visualizar a estrutura de atendimento da sua URA.

Parâmetros da estrutura da URA(dados)

O nome da "acao" é o maior e o que deve estar dentro do array "acao_dados" é o que vem logo abaixo. Veja o exemplo ao lado.

audio url_audio	Toca o áudio que consta na url. A url deve ser pública para que nosso sistema possa buscar.
tts mensagem	Toca a mensagem escrita em formato de áudio com uma voz simulada.
transfer numero_telefone	Transfere para um ramal ou número externo. Transferência para número externo tem o valor de uma ligação efetuada.
fila fila_id	Transfere para a fila de atendimento referente ao seu ID.
webhook url	Envia um webhook com as informações da chamada para o endpoint passado no parâmetro "url".
gotomenu menu	Vai para um próximo menu da mesma ura, exemplo "menu 2".
dinamico url	Encaminha a chamada para uma URA Dinâmica. Coloca-se a URL para onde será enviado um HTTP POST para solicitar a URA à ser carregada.
digiteramal mensagem	Mensagem que será reproduzida em formato de áudio ao cliente para solicitar a digitação de um ramal. A chamada será direcionada para o ramal informado.
fim	Derruba a ligação, não tem acao_dados e geralmente é usada seguido de uma outra ação. Se não tiver essa informação, a URA irá ficar até que o outro usuário desligue ou a ligação caia.

Parâmetros da estrutura da URA

Na tabela abaixo, você encontra todos os Parâmetros que podem ser utilizados.

Observações importantes: O nome da "acao" é o maior e o que deve estar dentro do array "acao_dados" é o que vem logo abaixo. Veja o exemplo ao lado.

audio url_audio	Toca o áudio que consta na url. A url deve ser pública para que nosso sistema possa buscar.
tts mensagem	Toca a mensagem escrita em formato de áudio com uma voz simulada.
transfer numero_telefone	Transfere para um ramal ou número externo. Transferência para número externo tem o valor de uma ligação efetuada.
fila fila_id	Transfere para a fila de atendimento referente ao seu ID.
webhook url	Envia um webhook com as informações da chamada para o endpoint passado no parâmetro "url".
gotomenu menu	Vai para um próximo menu da mesma ura, exemplo "menu 2".
dinamico url	Encaminha a chamada para uma URA Dinâmica. Coloca-se a URL para onde será enviado um HTTP POST para solicitar a URA à ser carregada.
digiteramal mensagem	Mensagem que será reproduzida em formato de áudio ao cliente para solicitar a digitação de um ramal. A chamada será direcionada para o ramal informado.
fim	Derruba a ligação, não tem acao_dados e geralmente é usada seguido de uma outra ação. Se não tiver essa informação, a URA irá ficar até que o outro usuário desligue ou a ligação caia.

Criar URA

Definição

POST https://voice-api.zenvia.com/ura

Request

curl -X POST --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: seu-token' \
             -d '{"nome":"Nome URA","dados":[{"acao":"tts","acao_dados":{"mensagem":"Essa é uma mensagem de Exemplo"}}]}' \
             'https://voice-api.zenvia.com/ura'

<?php
require_once "vendor/autoload.php";
use TotalVoice\Client as TotalVoiceClient;

$client = new TotalVoiceClient('seu-token');

$dados = array (
    0 => array (
      'acao' => 'tts',
      'menu' => 'menu 1',
      'acao_dados' => array (
          'mensagem' => 'Olá! Isso é um teste.'
      ),
    )
    );

$response = $client->central->criarUra("Teste TotalVoice-001", $dados);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

const dados = [{
    acao: "tts",
    opcao: "1",
    menu: "menu 2",
    acao_dados: {
        mensagem: "Mensagem de teste"
    }
}];

client.central.criarUra("nome-ura", dados)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
Em construção

client = Cliente("seu-token", 'voice-api.zenvia.com')
Em construção

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Em construção

require 'totalvoice-ruby'
include TotalVoice

Em construção

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "ura criada com sucesso",
  "dados": {
    "id": 1234
  }
}

Para criar uma URA, veja a lista de opções dos dados que podem ser utilizadas em Parâmetros da estrutura da URA

POST: https://voice-api.zenvia.com/ura

REQUEST:

• Headers

1. Content-Type: application/json
2. Authorization: Access-Token: seu-token

Veja ao lado um exemplo de requisição. Os campos são:

Request

nome string	Nome da URA
dados string	Dentro de dados você consegue passar a estrutura de atendimento da sua URA.

Response

id integer

Retorna o ID do Áudio

Buscar URA

Definição

GET https://voice-api.zenvia.com/ura/{id}

Request

curl -X GET --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: seu-token' \
             'https://voice-api.zenvia.com/ura/{id}'

<?php
require_once "vendor/autoload.php";
use TotalVoice\Client as TotalVoiceClient;

Em construção

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.central.buscaUra('id-ura')
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
Em construção

client = Cliente("seu-token", 'voice-api.zenvia.com')
Em construção

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Em construção

require 'totalvoice-ruby'
include TotalVoice

Em construção

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "id": 12345,
    "nome": "Atendimento ZenAPI",
    "dados": [
      {
        "timeout": 6,
        "menu": "menu 1",
        "opcao": "",
        "acao": "audio",
        "acao_dados": {
          "url_audio": "https://seuaud.io/1234.mp3"
        }
      },
      {
        "timeout_fila": 600,
        "menu": "menu 1",
        "opcao": "1",
        "acao": "fila",
        "acao_dados": {
          "fila_id": "123456"
        }
      }
    ]
  }
}

Caso deseje, após a criação de uma URA você poderá realizar a busca do registro pelo seu ID.

Para buscar, é necessário o envio da chave da fila na URL da requisição seguido da autenticação Acess Token no Header.

A chamada para obter os dados da consulta deve ser realizada utilizando um HTTP GET para o endereço de definição da API.

GET https://voice-api.zenvia.com/ura/{id}

Request

id integer

ID da URA

Response

dados object

Retorna o objeto da URA

Editar URA

Definição

PUT https://voice-api.zenvia.com/ura/{id}

Request

curl -X POST --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: seu-token' \
             -d '{"nome":"Nome URA","dados":[{"acao":"tts","acao_dados":{"mensagem":"Essa é uma mensagem de Exemplo 2"}}]}' \
             'https://voice-api.zenvia.com/ura/{id}'

<?php
require_once "vendor/autoload.php";
use TotalVoice\Client as TotalVoiceClient;

$client = new TotalVoiceClient('seu-token');

$dados = array (
    0 => array (
      'acao' => 'tts',
      'menu' => 'menu 1',
      'acao_dados' => array (
          'mensagem' => 'Olá! Isso é um teste.'
      ),
    )
    );

$response = $client->central->atualizarUra("123456", "Teste ZenAPI-001", $dados);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

const dados = {
    timeout: 10
};

client.central.atualizarUra('id-ura', 'nome-ura', dados)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
Em construção

client = Cliente("seu-token", 'voice-api.zenvia.com')
Em construção

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Em construção

require 'totalvoice-ruby'
include TotalVoice

Em construção

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "ura atualizada com sucesso",
  "dados": {
    "id": 1234
  }
}

Para alterar as informações de uma URA, o método de solicitação deve ser HTTP PUT. Ele criará um novo recurso e substituirá as antigas informações.

PUT https://voice-api.zenvia.com/ura/{id}

Request

nome string	Nome da URA
dados string	Estrutura de atendimento da URA.

Response

status object

Retorna o status da requisição

Deletar URA

Definição

DELETE https://voice-api.zenvia.com/ura/{id}

Request

curl -X DELETE --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: seu-token' \
             'https://voice-api.zenvia.com/ura/{id}'

<?php
require_once "vendor/autoload.php";
use TotalVoice\Client as TotalVoiceClient;

$client = new TotalVoiceClient('seu-token');

$response = $client->central->excluirUra("id");

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.central.excluirUra('id-ura')
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
Em construção

client = Cliente("seu-token", 'voice-api.zenvia.com')
Em construção

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Em construção

require 'totalvoice-ruby'
include TotalVoice

Em construção

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "URA Removida",
  "dados": null
}

Para deletar uma URA, basta informar o ID da mesma que deseja remover.

Método utilizado:

DELETE https://voice-api.zenvia.com/ura/{id}

Request

id integer

ID da URA

Response

status object

Retorna o status da requisição

Relatório URA

Definição

Retorna a sua lista de URAs e suas estruturas

GET https://voice-api.zenvia.com/ura/relatorio

Request

curl -X GET --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' \
            'https://voice-api.zenvia.com/ura/relatorio'

<?php
$client = new TotalVoiceClient('seu-token');
Em construção

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.central.relatorioUra()
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
Em construção

client = Cliente("seu-token", 'voice-api.zenvia.com')
Em construção

Em construção

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "relatorio": [
      {
        "id": 12345,
        "nome": "Teste Geral",
        "dados": [
          {
            "timeout": 6,
            "menu": "menu 1",
            "opcao": "",
            "acao": "tts",
            "acao_dados": {
              "mensagem": "Olá, seja bem vindo a melhór startap da Palhóça. Digite 1 para ser atendido."
            }
          },
          {
            "timeout_fila": 45,
            "menu": "menu 1",
            "opcao": "",
            "acao": "fila",
            "acao_dados": {
              "fila_id": "123456"
            }
          },
          {
            "timeout_fila": 9000,
            "menu": "menu 1",
            "opcao": "1",
            "acao": "fila",
            "acao_dados": {
              "fila_id": "745896"
            }
          }
        ]
      }
    ]
  }
}

Para consultar sua lista de URAs e suas estruturas, o método de solicitação deve ser HTTP GET. Ele retornará um array com as URAs e seus IDs.

GET https://voice-api.zenvia.com/ura/relatorio

Response

relatorio array

Retorna um array com as URAs e seus IDs e para cada uma um array com sua estrutura

APIs de Contas

Gerenciar Contas

Gerenciar Contas End Point

https://voice-api.zenvia.com/conta

Usando esse recurso, você pode criar, consultar, alterar e deletar contas filhas. As contas filhas são exatamente iguais a qualquer outra conta na Zenvia, se diferenciando apenas por serem vinculadas com uma conta pai que possui o controle sobre ela.

O intuito é o de realizar integrações e automatizar processos de uso e revenda de serviços da API.

Objeto Conta

JSON

{
    "id": 3132,
    "nome": "Zenvia Telecom",
    "cpf_cnpj": "00.000.000/0000-00",
    "login": "zenvia@zenvia.com",
    "saldo": 999.99,
    "telefone": "+5510999999999",
    "access_token": "seu-token",
    "preco_fixo": "0.060",
    "preco_cel": "0.350",
    "preco_ramal": "0.000",
    "email_financeiro": "zenvia@zenvia.com",
    "nome_fantasia": "Zenvia",
    "conta_ativa": 1,
    "valor_aviso_saldo_baixo": "150.00",
    "metodo_pagamento": "prepago",
    "fatura_atual": 0.00,
}

O objeto é um modelo JSON. Para realizar a chamada, é necessário que esta contenha os parâmetros solicitados abaixo na tabela Atributos. Ao final, a API fará o retorno.

Endpoint https://voice-api.zenvia.com/conta

Atributos

id integer	Identificador único da Conta.
login Obrigatório	Login para a nova conta, precisa ser um endereço de e-mail válido.
cpf_cnpj Obrigatório	CPF ou CNPJ desta conta, para fim de identificação e integração.
telefone Opcional	Número de telefone de contato desta conta, precisa ser um número de telefone válido.
preco_fixo Opcional	O valor que será cobrado desta conta para chamadas destinadas a números fixos, deve ser maior ou igual ao da conta pai, por padrão vem o valor igual ao atual.
preco_cel Opcional	O valor que será cobrado desta conta para chamadas destinadas a números móveis deve ser maior ou igual ao da conta pai, por padrão vem o valor igual ao atual.
preco_ramal Opcional	O valor que será cobrado desta conta para chamada entre Ramais dentro dela mesma deve ser maior ou igual ao valor da conta pai, por padrão vem o valor igual ao atual.
email_financeiro Opcional	E-mail de contato para assuntos financeiros da nova conta, por padrão vem o e-mail da conta pai.
nome_fantasia Opcional	Nome fantasia desta conta que será utilizado para exibição.
valor_aviso_saldo_baixo Opcional	É necessário sem um valor inteiro, ex: 100 .Quando o saldo de créditos atingir ou ficar abaixo do valor determinado, você receberá um aviso no email do email_financeiro(caso este não tenha sido cadastrado você receberá no e-mail de login

Criar Conta

Definição

POST https://voice-api.zenvia.com/conta

Request

curl 'https://voice-api.zenvia.com/conta' \
    -X POST \ 
    --header 'Content-Type: application/json' \
    --header 'Access-Token: seu-token' \
    -d '{"nome" : "Zenvia", "login" : "zenvia@zenvia.com", "senha" : "senha123"}'

<?php
$client = new TotalVoiceClient('seu-token');

$conta_dados = array(
    "nome" => "Zenvia", 
    "login" => "zenvia@zenvia.com", 
    "senha" => "senha123"
);
$response = $client->conta->criar($conta_dados);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

var conta_dados = {
    nome: "Zenvia", 
    login: "zenvia@zenvia.com", 
    senha: "senha123"
};

client.conta.criar(conta_dados)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")

conta = new(Conta)
conta.Nome = "Zenvia"
conta.Login = "zenvia@zenvia.com"
conta.Senha = "senha123"

response, err := client.Conta.Criar(conta)

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.conta.criar_conta("Zenvia", "zenvia@zenvia.com", "senha123")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Conta conta = new Conta(client);

JSONObject contaDados = new JSONObject();
contaDados.put("nome", "Zenvia");
contaDados.put("login", "zenvia@zenvia.com");
contaDados.put("senha", "senha123");

JSONObject response = conta.criar(contaDados);

Response

{
    "status": 200,
    "sucesso": true,
    "motivo": 0,
    "mensagem": "conta criada com sucesso",
    "dados": {
        "id": 3132,
        "access_token": "seu-token"
    }
}

Para criar uma conta filha, basta informar o nome da mesma e seguir os campos solicitados abaixo.

POST: https://voice-api.zenvia.com/conta

REQUEST:

• Headers

1. Content-Type: application/json
2. Authorization: Access-Token: seu-token

Veja ao lado um exemplo de requisição. Utilize os campos abaixo para informar à nossa API quais informações deseja enviar:

Request

nome Obrigatório	Nome para a nova conta filha.
login Obrigatório	Login para a nova conta, precisa ser um endereço de e-mail válido.
senha Obrigatório	Senha para esta nova conta. (Deve conter 8 caracteres, sendo pelo menos 1 maiúsculo e 1 minúsculo)
cpf_cnpj Obrigatório	CPF ou CNPJ desta conta, para fim de identificação e integração.
telefone Opcional	Número de telefone de contato desta conta, precisa ser um número de telefone válido.
preco_fixo Opcional	O valor que será cobrado desta conta para chamadas destinadas a números fixos, deve ser maior ou igual ao da conta pai, por padrão vem o valor igual ao atual.
preco_cel Opcional	O valor que será cobrado desta conta para chamadas destinadas a números móveis deve ser maior ou igual ao da conta pai, por padrão vem o valor igual ao atual.
preco_ramal Opcional	O valor que será cobrado desta conta para chamada entre Ramais dentro dela mesma deve ser maior ou igual ao valor da conta pai, por padrão vem o valor igual ao atual.
email_financeiro Opcional	E-mail de contato para assuntos financeiros da nova conta, por padrão vem o e-mail da conta pai.
nome_fantasia Opcional	Nome fantasia desta conta que será utilizado para exibição.
valor_aviso_saldo_baixo Opcional	É necessário sem um valor inteiro, ex: 100 .Quando o saldo de créditos atingir ou ficar abaixo do valor determinado, você receberá um aviso no email do email_financeiro(caso este não tenha sido cadastrado você receberá no e-mail de login

Response

id integer	Identificador único da conta criada.
access_token string	Token que deverá ser utilizado por esta nova conta para acessar os serviços da API.

Buscar Conta

Definição

GET https://voice-api.zenvia.com/conta/{id}

Request

curl 'https://voice-api.zenvia.com/conta/3132' \
    -X GET \
    --header 'Content-Type: application/json' \
    --header 'Access-Token: seu-token' 

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->conta->buscaConta(3132);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.conta.buscar(3132)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
response, err := client.Conta.Buscar(3132)

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.conta.get_by_id(3132)

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Conta conta = new Conta(client);

JSONObject response = conta.buscar(3132);

Response

{
    "status": 200,
    "sucesso": true,
    "motivo": 0,
    "mensagem": "dados retornados com sucesso",
    "dados": {
        "id": 3132,
        "nome": "Zenvia Telecom",
        "cpf_cnpj": "00.000.000/0000-00",
        "login": "zenvia@zenvia.com",
        "saldo": 999.99,
        "telefone": "+5510999999999",
        "access_token": "seu-token",
        "preco_fixo": "0.060",
        "preco_cel": "0.350",
        "preco_ramal": "0.000",
        "email_financeiro": "zenvia@zenvia.com",
        "nome_fantasia": "Zenvia",
        "conta_ativa": 1,
        "valor_aviso_saldo_baixo": "150.00",
        "metodo_pagamento": "prepago",
        "fatura_atual": 0.00,
    }
}

Caso deseje buscar detalhes de uma conta filha, basta realizar uma chamada para obter os dados. Utilize um HTTP GET para o endereço de definição da API.

GET https://voice-api.zenvia.com/conta{id}

Request

id Obrigatório

Identificador único da conta filha que você deseja buscar.

Response

dados object

Retorna o objeto Conta

Alterar Conta

Definição

PUT https://voice-api.zenvia.com/conta/{id}

Request

curl 'https://voice-api.zenvia.com/conta/3132' \
    -X PUT \
    --header 'Content-Type: application/json' \
    --header 'Access-Token: seu-token' \
    -d '{"senha" : "senha123456"}'

<?php
$client = new TotalVoiceClient('seu-token');

$conta_dados = array("senha" => "senha123456");
$response = $client->conta->atualizar(3132, $conta_dados);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

var conta_dados = {
    senha: "senha123456"
};
client.conta.atualizar(3132, conta_dados)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")

conta = new(Conta)
conta.senha = "senha123"

response, err := client.Conta.Atualizar(conta)

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.conta.editar_conta("Zenvia", "zenvia@zenvia.com", "senha123")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Conta conta = new Conta(client);

JSONObject contaDados = new JSONObject();
contaDados.put("id", 3132);
contaDados.put("senha", "senha123");

JSONObject response = conta.atualizar(contaDados);

Response

{
    "status": 200,
    "sucesso": true,
    "motivo": 0,
    "mensagem": "dados atualizados com sucesso",
    "dados": null
}

Para alterar as informações de uma conta já existente, você precisa passar na URL o ID da conta e no corpo do request o JSON com os campos que serão alterados, conforme os exemplos.

O método de solicitação deve ser HTTP PUT. Ele criará um novo recurso e substituirá as antigas informações.

PUT https://voice-api.zenvia.com/conta

Request

nome Opcional	Novo nome para a conta que você deseja alterar
login Opcional	Novo login para a conta, precisa ser um endereço de e-mail válido.
senha Opcional	Nova senha para esta conta. (Deve conter 8 caracteres, sendo pelo menos 1 maiúsculo e 1 minúsculo)
cpf_cnpj Opcional	Novo CPF ou CNPJ desta conta, para fim de identificação e integração.
telefone Opcional	Novo número de telefone de contato desta conta, precisa ser um número de telefone válido.
preco_fixo Opcional	O valor que será cobrado desta conta para chamadas destinadas a números fixos, deve ser maior ou igual ao da conta pai.
preco_cel Opcional	O valor que será cobrado desta conta para chamadas destinadas a números móveis deve ser maior ou igual ao da conta pai.
preco_ramal Opcional	O valor que será cobrado desta conta para chamada entre Ramais dentro dela mesma deve ser maior ou igual ao valor da conta pai.
email_financeiro Opcional	Novo e-mail de contato para assuntos financeiros desta conta.
nome_fantasia Opcional	Novo nome fantasia desta conta que será utilizado para exibição.
valor_aviso_saldo_baixo Opcional	É necessário sem um valor inteiro, ex: 100 .Quando o saldo de créditos atingir ou ficar abaixo do valor determinado, você receberá um aviso no email do email_financeiro(caso este não tenha sido cadastrado você receberá no e-mail de login

Response

Retorna o objeto resposta padrão da API com sucesso ou falha.

Deletar Conta

Definição

DELETE https://voice-api.zenvia.com/conta/{id}

Request

curl 'https://voice-api.zenvia.com/conta/3132' \
    -X DELETE \
    --header 'Content-Type: application/json' \
    --header 'Access-Token: seu-token' \

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->conta->excluir(3132);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.conta.excluir(3132)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
response, err := client.Conta.Excluir(3132)

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.conta.deletar(3132)

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Conta conta = new Conta(client);

JSONObject response = conta.excluir(3132);

Response

{
    "status": 200,
    "sucesso": true,
    "motivo": 0,
    "mensagem": "Conta Removida com sucesso.",
    "dados": null
}

Para deletar permanentemente uma conta filha, deixando-a indisponível para uma posterior consulta, basta informar o ID da mesma.

Método utilizado:

DELETE https://voice-api.zenvia.com/fila/{id}

Request

id Obrigatório

Identificador único da conta filha que você deseja deletar.

Response

Retorna o objeto resposta padrão da API com sucesso ou falha.

Relatório de Contas

Definição

GET https://voice-api.zenvia.com/conta/relatorio

Request

curl 'https://voice-api.zenvia.com/conta/relatorio' \
    -X GET \
    --header 'Content-Type: application/json' \
    --header 'Access-Token: seu-token' 

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->conta->relatorio();

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.conta.relatorio()
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
response, err := client.Conta.Relatorio.Gerar()

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.conta.get_relatorio()

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Conta conta = new Conta(client);

JSONObject response = conta.relatorio();

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "relatorio": [
      {
        "id": 3132,
        "nome": "Zenvia Telecom",
        "cpf_cnpj": "00.000.000/0000-00",
        "login": "zenvia@zenvia.com",
        "saldo": 999.99,
        "telefone": "+5510999999999",
        "access_token": "testeM68PU1Izmb9chEdLzep7IwRymWO",
        "preco_fixo": "0.060",
        "preco_cel": "0.350",
        "preco_ramal": "0.000",
        "email_financeiro": "zenvia@zenvia.com",
        "nome_fantasia": "Zenvia",
        "conta_ativa": 1,
        "valor_aviso_saldo_baixo": "150.00",
        "metodo_pagamento": "prepago",
        "fatura_atual": 0.00,
      },
      {
        "id": 3132,
        "nome": "Zenvia Telecom",
        "cpf_cnpj": "00.000.000/0000-00",
        "login": "zenvia@zenvia.com",
        "saldo": 999.99,
        "telefone": "+5510999999999",
        "access_token": "testeM68PU1Izmb9chEdLzep7IwRymWO",
        "preco_fixo": "0.060",
        "preco_cel": "0.350",
        "preco_ramal": "0.000",
        "email_financeiro": "zenvia@zenvia.com",
        "nome_fantasia": "Zenvia",
        "conta_ativa": 1,
        "valor_aviso_saldo_baixo": "150.00",
        "metodo_pagamento": "prepago",
        "fatura_atual": 0.00
      }
    ]
  }
}

Para consultar os dados da sua conta e retornar um relatório com todas as suas contas filhas, veja ao lado um exemplo de requisição.

As contas retornadas no relatório vêm ordenadas por data de criação.

Response

relatorio array

Retorna um array com objetos conta

Crédito bônus

Definição

POST https://voice-api.zenvia.com/conta/{id}/bonus

Request

curl -X POST --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' \
            -d '{"valor":"100"}' \
            'https://voice-api.zenvia.com/conta/id-conta/bonus'

Em Contrução

Em Contrução

Em Contrução

Em Contrução

Em Contrução

Em Contrução

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "valor adicionado com sucesso"
}

Para adicionar crédito de bônus nas contas criadas, veja ao lado um exemplo de requisição.

Request

id Obrigatório	ID da conta que vai receber os creditos
valor Obrigatório	Valor que será adicionado como crédito bônus na conta

Webhooks

A seguir, veja quais métodos de Webhooks estão disponíveis para a API de Gerenciar Contas.

Caso ainda não tenha configurado nenhum evento no nosso Painel de Voz, recomendamos a leitura desta documentação técnica.

Listar Webhooks

Definição

GET https://voice-api.zenvia.com/conta/webhook-default

Request

curl -X GET --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: {{access-token}}' \
            'https://voice-api.zenvia.com/conta/webhook-default'

<?php
$response = $client->conta->webhooksDefault();

var response = client.conta.webhooksDefault()

client := totalvoice.NewTotalVoiceClient("Seu_Token")
response, err := client.WebhookDefault.Listar();

from totalvoice.cliente import Cliente

client = Cliente("Seu_Token", 'voice-api.zenvia.com')
response = client.conta.get_webhook_default()

Conta conta = new Conta(client);
JSONObject response = conta.webhookDefault()

puts @client.conta.webhooks_default()

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "webhooks": [
      {
        "webhook": "status_tempo_real",
        "url": "https://webhook.site/T3st1dew3b400k"
      },
      {
        "webhook": "chamada_fim",
        "url": "https://webhook.site/T3st1dew3b400k"
      },
    ]
  }
}

Este método permite a listagem de todos os webhooks default configurados para suas subcontas (Contas filhas).

Request

Não precisa passar nenhum parâmetro.

Response

webhooks array

Retorna dentro de dados um arrays com os webhooks default cadastros.

Remover Webhooks

Definição

DELETE https://voice-api.zenvia.com/conta/webhook-default/{nome_webhook}

Request

curl -X DELETE --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: {{access-token}}' \
            'https://voice-api.zenvia.com/conta/webhook-default/chamada_fim'

<?php
$response = $client->conta->excluirWebhookDefault("nome");

var response = client.conta.excluirWebhookDefault("nome")

client := totalvoice.NewTotalVoiceClient("Seu_Token")
response, err := client.WebhookDefault.Excluir("nome")

from totalvoice.cliente import Cliente

client = Cliente("Seu_Token", 'voice-api.zenvia.com')
client.conta.delete_webhook_default("nome")

Conta conta = new Conta(client);
JSONObject response = conta.excluirWebhookDefault("nome");

puts @client.conta.excluir_webhook_default("nome")

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "webhook default apagado com sucesso",
  "dados": null
}

Este método permite a remoção de um webhook default específico.

Request

webhook string

Nome do webhook

Response

dados string

Retorna dados null e mensagem de sucesso

Alterar um webhook

Definição

PUT https://voice-api.zenvia.com/conta/webhook-default/{nome_webhook}

Request

curl 'https://voice-api.zenvia.com/conta/webhook-default/chamada_fim' \
    -X PUT \
    --header 'Content-Type: application/json' \
    --header 'Access-Token: Seu_Token' \
    -d '{"url" : "www.urlretorno.com.br"}'

<?php
$client = new TotalVoiceClient('Seu_Token');
$response = $client->conta->salvaWebhookDefault("nome","url")

const totalvoice = require('totalvoice-node');
const client = new totalvoice("Seu_Token");

client.conta.salvaWebhookDefault("nome","url")

client := totalvoice.NewTotalVoiceClient("Seu_Token")
response, err := client.WebhookDefault.Salvar("nome","url");

from totalvoice.cliente import Cliente

client = Cliente("Seu_Token", 'voice-api.zenvia.com')
response = client.conta.edit_webhook_default("nome","url")

TotalVoiceClient client = new TotalVoiceClient("Seu_Token");
Conta conta = new Conta(client);
JSONObject response = conta.salvarWebhookDefault("nome","url");

puts @client.conta.salvar_webhook_default("nome","url")

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "webhook default atualizado com sucesso",
  "dados": null
}

Este método permite alterar as informações de um webhook default. Para isso, antes você precisa passar no corpo do request o JSON com a url que vai receber o webhook.

Request

nome string	Nome do webhook que vai ser alterado
url string	Sua URL que vai receber o callback

Response

dados string

Retorna dados null e mensagem de sucesso

Minha conta

Usando esse recurso, você pode visualizar seu saldo, monitorar suas contas e suas recargas, editar suas contas e configurar e visualizar seus webhooks.

Objeto Minha Conta

JSON

{
    "id": 1,
    "nome": "Zenvia Telecom",
    "cpf_cnpj": "12.123.123\/0001-10",
    "login": "teste@zenvia.com",
    "saldo": 950.64,
    "telefone": "+5510999999999",
    "access_token": "1234asdkgh1g23213nkbdfsh3v43",
    "preco_fixo": "0.060",
    "preco_sms": "0.090",
    "preco_cel": "0.350",
    "preco_ramal": "0.000",
    "email_financeiro": "testefinanceiro@zenvia.com",
    "nome_fantasia": null,
    "conta_ativa": 1,
    "valor_aviso_saldo_baixo": "0.00",
    "metodo_pagamento": "prepago",
    "fatura_atual": 1.52,
    "limite_credito_bonus": 0
}

O objeto é um modelo JSON. Para realizar a chamada, é necessário que esta contenha os parâmetros solicitados abaixo na tabela Atributos. Ao final, a API fará o retorno.

Endpoint https://voice-api.zenvia.com/conta

Atributos

nome string	Nome da conta.
login string	Login de acesso da sua conta
cpf_cnpj string	CPF ou CNPJ da sua conta
telefone string	Telefone da sua conta
preco_fixo string	Preço por minuto do fixo
preco_cel string	Preço por minuto para celular
preco_ramal string	Preço por minuto do ramal
email_financeiro string	E-mail do financeiro da sua empresa
nome_fantasia string	Nome fantasia da sua empresa

Objeto Resposta - Minha conta

JSON

{
    "id": 1,
    "nome": "Zenvia Telecom",
    "cpf_cnpj": "12.123.123\/0001-10",
    "login": "teste@zenvia.com",
    "saldo": 950.64,
    "telefone": "+5510999999999",
    "access_token": "1234asdkgh1g23213nkbdfsh3v43",
    "preco_fixo": "0.060",
    "preco_sms": "0.090",
    "preco_cel": "0.350",
    "preco_ramal": "0.000",
    "email_financeiro": "testefinanceiro@zenvia.com",
    "nome_fantasia": null,
    "conta_ativa": 1,
    "valor_aviso_saldo_baixo": "0.00",
    "metodo_pagamento": "prepago",
    "fatura_atual": 1.52,
    "limite_credito_bonus": 0
}

O objeto é um modelo JSON. Para realizar a chamada, é necessário que esta contenha os parâmetros solicitados abaixo na tabela Atributos. Ao final, a API fará o retorno.

Endpoint https://voice-api.zenvia.com/conta

Atributos

id integer	ID do registro da sua conta
nome string	Nome da sua conta
cpf_cnpj string	CPF ou CNPJ da sua conta
login string	Login de acesso da sua conta
saldo float	Saldo atual da conta
telefone string	Telefone da sua conta
access_token string	Access Token da sua conta
preco_fixo string	Preço por minuto para fixo
preco_cel string	Preço por minuto para celulares
preco_ramal string	Preço por minuto para ramal
email_financeiro string	E-mail do financeiro da sua empresa
nome_fantasia string	Nome fantasia da sua empresa
metodo_pagamento string	Método de faturamento da sua conta

Consultar saldo da Conta

Definição

GET https://voice-api.zenvia.com/saldo

Request

curl -X GET --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: {{access-token}}' \
            'https://voice-api.zenvia.com/saldo'

<?php
$response = $client->perfil->consultaSaldo();

var response = client.perfil.consultaSaldo()

client := totalvoice.NewTotalVoiceClient("Seu_Token")

 response, err := client.Saldo.ConsultaSaldo()

from totalvoice.cliente import Cliente

client = Cliente("Seu_Token", 'voice-api.zenvia.com')
response = client.minha_conta.get_saldo()

Perfil perfil = new Perfil(client);
JSONObject response = perfil.consultaSaldo();

puts @client.perfil.consulta_saldo()

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "saldo atual",
  "dados": {
    "saldo": 100.00
  }
}

Caso deseje consultar o saldo disponível em sua conta, basta realizar uma chamada para obter os dados. Utilize um HTTP GET para o endereço de definição da API.

GET https://voice-api.zenvia.com/saldo

Buscar conta

Definição

GET https://voice-api.zenvia.com/conta/

Request

curl -X GET --header 'Content-Type: application/json' \
            --header 'Accept: application/json' \
            --header 'Access-Token: {{access-token}}' 'https://voice-api.zenvia.com/conta'

<?php
$response = $client->perfil->minhaConta();

var response = client.perfil.minhaConta()

client := totalvoice.NewTotalVoiceClient("Seu_Token")

 response, err := client.Perfil.MinhaConta()

from totalvoice.cliente import Cliente

client = Cliente("Seu_Token", 'voice-api.zenvia.com')
response = client.minha_conta.get_conta()

Perfil perfil = new Perfil(client);
JSONObject response = perfil.minhaConta();

puts @client.perfil.minha_conta()

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "id": 1,
    "nome": "Zenvia Telecom",
    "cpf_cnpj": "12.123.123\/0001-10",
    "login": "teste@zenvia.com",
    "saldo": 950.64,
    "telefone": "+5510999999999",
    "access_token": "1234asdkgh1g23213nkbdfsh3v43",
    "preco_fixo": "0.060",
    "preco_sms": "0.090",
    "preco_cel": "0.350",
    "preco_ramal": "0.000",
    "email_financeiro": "testefinanceiro@zenvia.com",
    "nome_fantasia": null,
    "conta_ativa": 1,
    "valor_aviso_saldo_baixo": "0.00",
    "metodo_pagamento": "prepago",
    "fatura_atual": 1.52,
    "limite_credito_bonus": 0
  }
}

Caso deseje buscar a sua conta, basta realizar uma chamada para obter os dados. Utilize um HTTP GET para o endereço de definição da API.

GET https://voice-api.zenvia.com/conta

Alterar Conta

Definição

PUT https://voice-api.zenvia.com/conta

Request

curl 'https://voice-api.zenvia.com/conta/3132' \
    -X PUT \
    --header 'Content-Type: application/json' \
    --header 'Access-Token: Seu_Token' \
    -d '{"senha" : "senha123456"}'

<?php
$client = new TotalVoiceClient('Seu_Token');

$conta_dados = array("senha" => "senha123456");
$response = $client->perfil->atualizaDadosConta($conta_dados);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("Seu_Token");

var conta_dados = {
    senha: "senha123456"
};
client.perfil.atualizaDadosConta(conta_dados)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("Seu_Token")

perfil = new(Perfil)
perfil.NomeFantasia = "NovoNome"

response, err := client.Perfil.AtualizarConta(perfil)

from totalvoice.cliente import Cliente

client = Cliente("Seu_Token", 'voice-api.zenvia.com')
response = client.perfil.editar_conta("Zenvia")

TotalVoiceClient client = new TotalVoiceClient("Seu_Token");
Perfil perfil = new Perfil(client);
JSONObject response = perfil.atualizaDadosConta('{"nome":"TotalVoice"}');

puts @client.perfil.atualizar('{"nome":"TotalVoice"}')

Response

{
    "status": 200,
    "sucesso": true,
    "motivo": 0,
    "mensagem": "dados atualizados com sucesso",
    "dados": null
}

Para alterar as informações da sua conta principal, você precisa passar no corpo do request o JSON com os campos que serão alterados, conforme os exemplos.

O método de solicitação deve ser HTTP PUT. Ele criará um novo recurso e substituirá as antigas informações.

PUT https://voice-api.zenvia.com/conta

Request

nome Opcional	Novo nome para a conta que você deseja alterar
login Opcional	Novo login para a conta, precisa ser um endereço de e-mail válido.
senha Opcional	Nova senha para esta conta. (Deve conter 8 caracteres, sendo pelo menos 1 maiúsculo e 1 minúsculo)
cpf_cnpj Opcional	Novo CPF ou CNPJ desta conta, para fim de identificação e integração.
telefone Opcional	Novo número de telefone de contato desta conta, precisa ser um número de telefone válido.
preco_fixo Opcional	O valor que será cobrado desta conta para chamadas destinadas a números fixos deve ser maior ou igual ao da conta pai.
preco_cel Opcional	O valor que será cobrado desta conta para chamadas destinadas a números móveis, deve ser maior ou igual ao da conta pai.
preco_ramal Opcional	O valor que será cobrado desta conta para chamada entre Ramais dentro dela mesma deve ser maior ou igual ao valor da conta pai.
email_financeiro Opcional	Novo e-mail de contato para assuntos financeiros desta conta.
nome_fantasia Opcional	Novo nome fantasia desta conta que será utilizado para exibição.

Response

Retorna o objeto resposta padrão da API com sucesso ou falha.

Relatório de Recarga

Definição

GET https://voice-api.zenvia.com/conta/recargas

Request

curl -X GET --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: {{access-token}}' \
            'https://voice-api.zenvia.com/conta/recargas'

<?php
$response = $client->perfil->relatorioRecarga();

var response = client.perfil.relatorioRecarga();

client := totalvoice.NewTotalVoiceClient("Seu_Token")

 response, err := client.Perfil.RelatorioRecarga()

from totalvoice.cliente import Cliente

client = Cliente("Seu_Token", 'voice-api.zenvia.com')
response = client.minha_conta.get_recargas()

Perfil perfil = new Perfil(client);
JSONObject response = perfil.relatorioRecarga();

puts @client.perfil.relatorio_recarga()

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "relatorio": [
      {
        "id": 6470,
        "credito": 10,
        "data": "2018-07-05T09:42:03-03:00",
        "descricao": "Recarga"
      },
      {
        "id": 5873,
        "credito": 10,
        "data": "2018-05-28T11:34:49-03:00",
        "descricao": "Recarga"
      }
    ]}
}

Para consultar os dados de recarga da sua conta, basta informar o período desejado para que a API retorne os dados.

Veja ao lado um exemplo de requisição. Os campos são:

Response

id integer	ID da transação de recarga
credito float	Valor da recarga
data datetime	Data da transação
descricao string	Descrição da transação

URL de recarga

Definição

GET https://voice-api.zenvia.com/conta/urlrecarga

Request

curl -X GET --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: {{access-token}}' \
            'https://voice-api.zenvia.com/conta/urlrecarga?url_retorno=www.urlretorno.com.br'

<?php
$response = $client->perfil->urlRecarga("www.urlretorno.com.br");

var response = client.perfil.urlRecarga("www.urlretorno.com.br");

client := totalvoice.NewTotalVoiceClient("Seu_Token")

 response, err := client.Perfil.GeraURLRecarga("www.urlretorno.com.br")

from totalvoice.cliente import Cliente

client = Cliente("Seu_Token", 'voice-api.zenvia.com')
response = client.minha_conta.get_url_recarga("www.urlretorno.com.br")

Perfil perfil = new Perfil(client);
JSONObject response = perfil.urlRecarga("www.urlretorno.com.br");

puts @client.perfil.url_recarga("www.urlretorno.com.br")

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "url": "https://api.evoline.com.br/recarga/index.php?id=eagr&public_key=teste5a4b033e14e69"
  }
}

Para gerar uma URL para recarga de créditos na sua conta, utilize um HTTP GET no endereço de definição da API.

GET https://voice-api.zenvia.com/conta/urlrecarga

APIs de Ligações

Chamadas

Usando esse recurso, será possível criar chamadas perna A e perna B, podendo gravar as ligações, agendar e binar o seu próprio número.

Além disso, também permite:

• Gerar relatório de chamadas;
• Derrubar chamadas em andamento;
• Transferir chamadas;
• Obter avaliação de chamadas.

Objeto Chamadas

JSON

{
    "id": 123,
    "data_criacao": "2018-08-02T10:49:30-03:00",
    "ativa": false,
    "url_gravacao": "https://urlgravacao.com.br/rec/audio.mp3",
    "cliente_id": 1,
    "conta_id": 1,
    "ramal_id_origem": 1,
    "tags": "minha-tags",
    "status_geral": "finalizada",
    "origem": {
      "data_inicio": null,
      "numero": "4000",
      "tipo": "ramal",
      "status": "atendida",
      "duracao_segundos": 10,
      "duracao": "00:00:10",
      "duracao_cobrada_segundos": 10,
      "duracao_cobrada": "00:00:10",
      "duracao_falada_segundos": 10,
      "duracao_falada": "00:00:10",
      "preco": 0.1,
      "motivo_desconexao": "indefinido"
    },
    "destino": {
      "data_inicio": "2018-08-02T10:49:29-03:00",
      "numero": "4001",
      "tipo": "ramal",
      "status": "atendida",
      "duracao_segundos": 29,
      "duracao": "00:00:29",
      "duracao_cobrada_segundos": 60,
      "duracao_cobrada": "00:01:00",
      "duracao_falada_segundos": 28,
      "duracao_falada": "00:00:28",
      "preco": 0.1,
      "motivo_desconexao": "indefinido"
    }
 }

O objeto é um modelo JSON que retorna informações sobre as chamadas.

É necessário conter os parâmetros solicitados abaixo na tabela Atributos para, ao final, a API fazer o retorno.

Endpoint: https://voice-api.zenvia.com/chamada

Atributos

id integer	ID do registro da chamada.
data_criacao datetime	Data de criação do registro da chamada. Data e Hora no formato UTC
ativa boolean	Identifica se a chamada está ativa ou não
url_gravacao string	URL com áudio da gravação da chamada
cliente_id integer	Identificação do cliente referente a chamada
conta_id integer	Identificação da Conta referente a chamada
ramal_id_origem integer	ID do ramal que originou a chamada referente a ligação, se houver.
tags string	Informação adicional que pode ser retornada no objeto, como um ID Externo por exemplo. Você consegue enviar essa informação no Post da Chamada e recuperar posteriormente nessa consulta.
detecta_caixa boolean	Caso identificado caixa, a ligação será derrubada antes que a ligação seja atendida. Esse serviço tem um custo adicional.
status_geral string	Status geral da Chamada. criada: chamada foi criada curso: está em andamento finalizada: chamada foi finalizada
origem / destino object	Retorna os objetos origem/destino

Objeto Origem/Destino

JSON

{
  "data_inicio": "2018-08-02T10:49:29-03:00",
  "numero": "4000",
  "tipo": "ramal",
  "status": "atendida",
  "duracao_segundos": 29,
  "duracao": "00:00:29",
  "duracao_cobrada_segundos": 60,
  "duracao_cobrada": "00:01:00",
  "duracao_falada_segundos": 28,
  "duracao_falada": "00:00:28",
  "preco": 0,
  "motivo_desconexao": "indefinido"
}

O objeto é um modelo JSON que retorna informações sobre a origem de quem originou a ligação e o destino de quem recebeu.

Nestes dois objetos você encontrará as informações sobre duração das chamadas, status e preço que foi cobrado por cada perna.

É necessário conter os parâmetros solicitados abaixo na tabela Atributos para, ao final, a API fazer o retorno.

Endpoint: https://voice-api.zenvia.com/chamada

Atributos

data_inicio datetime	Data e hora de início da chamada na Origem/Destino.
numero string	Número que irá receber a ligação e será o número de Origem/Destino.
tipo string	Tipo da ligação: ramal: ligação para um ramal movel: ligação para um celular fixo: ligação para um número fixo
status string	Status da ligação na Origem/Destino: atendida sem resposta ocupado congestionado falha cancelada não existe
duracao_segundos integer	Duração em segundos (inteiro) do total da chamada desde o início do processamento
duracao integer	Duração total da chamada desde o início do processamento
duracao_cobrada_segundos integer	Duração em segundos para fins de cobrança
duracao_cobrada integer	Duração considerada para fins de cobrança
duracao_falada_segundos integer	Duração em segundos da chamada desde que o destino atendeu
duracao_falada integer	Duração da chamada desde que o destino atendeu
preco float	Valor cobrado pela chamada
motivo_desconexao string	Um dos motivos de desconexão: 1. telefone não existe 2. sem rota para a rede de destino 3. sem rota para o destino 4. prefixo incorreto 6. canal inaceitável 7. chamada sendo entregue em canal ja estabelecido 8. call peemption 14. telefone portado para outra operadora 16. normal 17. ocupado 18. sem resposta 19. sem resposta - mas chamou 20. assinante ausente 21. chamada rejeitada 22. este número mudou 23. redirecionado para novo destino 26. atendido em outro lugar 27. destino não está funcionando 28. formato inválido de número 29. rejeitado 30. resposta para status enquiry 31. normal, não especificado 34. sem canal disponível 41. falha temporária 42. equipamento congestionado 44. canal requisitado não está disponível 50. não cadastrado 52. chamada sainte barrada 54. chamada entrante barrada 57. capacidade não autorizada 58. erro de mídia ou parâmetros incompatíveis 65. capacidade do portador não implementada 66. tipo de canal não implementado 69. não implementado 81. valor de referência inválido 88. destino incompatível 95. mensagem inválida não especificada 96. informação obrigatória não presente 97. mensagem não implementada 98. mensagem não compatível com o estado da chamada não existente ou não implementada 97. mensagem não implementada 99. elemento não existente ou não implementada 97. mensagem não implementada 100. informação inválida no conteúdo dos elementos 101. mensagem não compatível com o estado da chamada 102. timeout 111. erro de protocolo 127. erro de conectividade

Criar Chamada

Definição

POST https://voice-api.zenvia.com/chamada

Request

curl -X POST --header 'Content-Type: application/json' 
             --header 'Accept: application/json' 
             --header 'Access-Token: seu-token' 
             -d '{
                    "numero_origem":"+5510999999999",
                    "numero_destino":"+5510999999999",
                    "data_criacao":"2021-04-08T17:21:20Z",
                    "gravar_audio":"true",
                    "bina_origem":"+5510888888888",
                    "bina_destino":"+5510888888888",
                    "tags":"clienteUm",
                    "detecta_caixa_origem":"true"
                 }' 
             'https://voice-api.zenvia.com/chamada'

<?php
$client = new TotalVoiceClient('seu-token');

$response = $client->chamada->ligar('+5510999999999', '+5510999999999');

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.chamada.ligar("+5510999999999", "+5510999999999")
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.Chamada.Criar("+5510999999999", "+5510999999999", nil)

from totalvoice.cliente import Cliente

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.chamada.enviar("+5510999999999", "+5510999999999")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Chamada chamada = new Chamada(client);

JSONObject response = chamada.ligar("+5510999999999", "+5510999999999");

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.chamada.ligar("+5510999999999", "+5510999999999")

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "chamada criada com sucesso",
  "dados": {
    "id": 123123
  }
}

Para criar uma chamada, basta informar o número de origem e o destino.

POST: https://voice-api.zenvia.com/chamada

REQUEST:

• Headers

1. Content-Type: application/json
2. Authorization: Access-Token: seu-token

Veja ao lado um exemplo de requisição. Utilize os campos abaixo para informar à nossa API as informações que irá enviar:

Request

numero_origem Obrigatório string	Número origem (perna A), recebe a chamada primeiro do número destino. Formato E.164: [+][DDI][DDD][Número] Exemplo: +5510999999999
numero_destino Obrigatório string	Número destino (perna B), recebe a chamada após o número origem atender. Formato E.164: [+][DDI][DDD][Número] Exemplo: +5510999999999
data_criacao Opcional string	Informe uma data e hora para agendar a chamada. vazio = liga imediatamente. Data e Hora no formato UTC
gravar_audio Opcional boolean	Flag que indica se o áudio da ligação deve ser gravado
bina_origem Opcional string	Número de BINA que será apresentado na chamada para o número origem (perna A). Formato E.164: [+][DDI][DDD][Número], exemplo: +5510999999999
bina_destino Opcional string	Número de BINA que será apresentado na chamada para o número destino (perna B). Formato E.164: [+][DDI][DDD][Número], exemplo: +5510999999999
tags Opcional string	Tags ou comentários sobre esta chamada
detecta_caixa_origem Opcional boolean	Desconecta automaticamente em até 3s caso caia em caixa postal (vivo, claro, tim, oi)

Response

id integer

Retorna o ID da chamada

Desligar Chamada

Definição

POST https://voice-api.zenvia.com/chamada/{id}

Request

curl -X DELETE --header 'Content-Type: application/json' \
               --header 'Accept: application/json' \
               --header 'Access-Token: seu-token' \
               'https://voice-api.zenvia.com/chamada/123'

<?php
$client = new TotalVoiceClient('seu-token');

$response = $client->chamada->encerrar(123);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.chamada.encerrar(123)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
response, err := client.Chamada.Encerrar(123)

from totalvoice.cliente import Cliente

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.chamada.deletar("123")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Chamada chamada = new Chamada(client);

JSONObject response = chamada.encerrar(123);

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.chamada.encerrar("+5510999999999", "http://foo.bar/audio.mp3")

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "encerrando chamada",
  "dados": null
}

Para desligar uma chamada, basta informar o ID da mesma.

Método utilizado:

POST https://voice-api.zenvia.com/chamada/{id}

Request

id integer

ID da chamada ativa

Buscar Chamada

Definição

GET https://voice-api.zenvia.com/chamada/{id}

Request

curl -X GET --header 'Content-Type: application/json' \
            --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' 'https://voice-api.zenvia.com/chamada/123'

<?php
$client = new TotalVoiceClient('seu-token');

$response = $client->chamada->buscaChamada(123);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.chamada.buscar(123)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.Chamada.Buscar(123)

from totalvoice.cliente import Cliente

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.chamada.get_by_id("123")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Chamada chamada = new Chamada(client);

JSONObject response = chamada.buscar(123);

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.chamada.buscar(123)

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
     "id": 123,
     "data_criacao": "2018-08-02T10:49:30-03:00",
     "ativa": false,
     "url_gravacao": "https://urlgravacao.com.br/rec/audio.mp3",
     "cliente_id": 1,
     "conta_id": 1,
     "ramal_id_origem": 1,
     "tags": "minha-tags",
     "status_geral": "finalizada",
     "origem": {
       "data_inicio": null,
       "numero": "4000",
       "tipo": "ramal",
       "status": "atendida",
       "duracao_segundos": 10,
       "duracao": "00:00:10",
       "duracao_cobrada_segundos": 10,
       "duracao_cobrada": "00:00:10",
       "duracao_falada_segundos": 10,
       "duracao_falada": "00:00:10",
       "preco": 0.1,
       "motivo_desconexao": "indefinido",
       "bina_origem" : "+5510888888888 "
     },
     "destino": {
       "data_inicio": "2018-08-02T10:49:29-03:00",
       "numero": "4001",
       "tipo": "ramal",
       "status": "atendida",
       "duracao_segundos": 29,
       "duracao": "00:00:29",
       "duracao_cobrada_segundos": 60,
       "duracao_cobrada": "00:01:00",
       "duracao_falada_segundos": 28,
       "duracao_falada": "00:00:28",
       "preco": 0.1,
       "motivo_desconexao": "indefinido",
       "bina_destino" : "+5510888888888 "
     }
  }
}

Para buscar uma chamada, basta informar o ID da mesma após o seu envio.

Método utilizado:

GET https://voice-api.zenvia.com/chamada/{id}

Request

ID Obrigatório

ID da chamada para recuperar os dados

Response

dados object

Retorna o objeto chamada

Buscar gravação da Chamada

Definição

GET https://voice-api.zenvia.com/chamada/{id}/gravacao

Request

curl -X GET --header 'Content-Type: application/json' \
            --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' 'https://voice-api.zenvia.com/chamada/1/gravacao'

<?php
$client = new TotalVoiceClient('seu-token');

$response = $client->chamada->downloadGravacao(123);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.chamada.downloadGravacao(123)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.Chamada.DownloadGravacao(123)

from totalvoice.cliente import Cliente

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.chamada.get_gravacao_chamada("123")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Chamada chamada = new Chamada(client);

JSONObject response = chamada.downloadGravacao(123);

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.chamada.download_gravacao(123)

Response

{
  "access-control-allow-origin": "*",
  "connection": "Keep-Alive",
  "content-length": "1",
  "content-type": "audio/mpeg",
  "date": "Thu, 02 Aug 2018 19:06:54 GMT",
  "keep-alive": "timeout=5, max=100"
}

Para buscar uma gravação e realizar o download do áudio da chamada, é preciso antes setar a opção "Gravar Audio" igual a True no momento da criação da chamada.

Método utilizado:

GET https://voice-api.zenvia.com/chamada/{id}/gravacao

Veja ao lado um exemplo de requisição. Os campos são:

Request

ID Obrigatório

ID da chamada para recuperar os dados da gravação

Response

response header

Irá retornar um HTTP Response com Cabeçalho de Resposta: Content-Type: "audio/mpeg"

Relatório Chamadas

Definição

GET https://voice-api.zenvia.com/chamada/relatorio

Request

curl -X GET --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' \
            'https://voice-api.zenvia.com/chamada/relatorio?data_inicio=2018-03-14&data_fim=2018-03-15'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->chamada->relatorio($dataInicial, $dataFinal, $filtros);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.chamada.relatorio(dataInicial, dataFinal, filtros)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
response, err := client.Chamada.Relatorio.Gerar(dataInicial, dataFinal, filtros)

from totalvoice.cliente import Cliente

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.chamada.get_relatorio("2017-12-08T11:00:32-02:00", "2017-12-08T11:00:32-02:00")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Chamada chamada = new Chamada(client);
JSONObject response = chamada.relatorio(dataInicial, dataFinal, filtros);

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.chamada.relatorio(data_inicial, data_final, filtros)

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "relatorio": [
      {
        "id": 123,
        "data_criacao": "2018-08-02T10:32:22-03:00",
        "ativa": false,
        "url_gravacao": "https://urlgravacao.com.br/rec/audio.mp3",
        "cliente_id": 1,
        "conta_id": 1,
        "ramal_id_origem": 16,
        "tags": null,
        "status_geral": "finalizada",
        "origem": {
          "data_inicio": null,
          "numero": "4000",
          "tipo": "ramal",
          "status": null,
          "duracao_segundos": 0,
          "duracao": "00:00:00",
          "duracao_cobrada_segundos": 0,
          "duracao_cobrada": "00:00:00",
          "duracao_falada_segundos": 0,
          "duracao_falada": "00:00:00",
          "preco": 0,
          "motivo_desconexao": "indefinido",
          "bina_origem" : "+5510888888888 "
        },
        "destino": {
          "data_inicio": "2018-08-02T10:32:22-03:00",
          "numero": "4001",
          "tipo": "ramal",
          "status": "atendida",
          "duracao_segundos": 8,
          "duracao": "00:00:08",
          "duracao_cobrada_segundos": 60,
          "duracao_cobrada": "00:01:00",
          "duracao_falada_segundos": 8,
          "duracao_falada": "00:00:08",
          "preco": 0,
          "motivo_desconexao": "indefinido",
          "bina_destino" : "+5510888888888 "

        }
      }
    ]
  }
}

Para consultar as chamadas enviadas,, basta informar o período desejado para que a API retorne os dados.

Veja ao lado um exemplo de requisição. Os campos são:

Request

data_inicio Obrigatório Query String	Data inicial para consulta dos dados no relatório
data_fim Obrigatório Query String	Data final para consulta dos dados no relatório
origem Opcional Query String	Número de telefone de origem para filtrar. Formato E.164: [+][DDI][DDD][Número]. Ex.: +5510999999999
destino Opcional Query String	Número de telefone de destino para filtrar. Formato E.164: [+][DDI][DDD][Número]. Ex.: +5510999999999
posicao Opcional Query String	Posição para seleção dos dados do relatório - começa na posição 0. Também chamado de offset.
limite Opcional Query String	Quantidade de chamadas a retornar na consulta. O limite padrão é 100 e o máximo é 200.

Response

relatorio array

Retorna um array com objetos chamada

Escutar Chamadas

Definição

GET https://voice-api.zenvia.com/chamada/{id}/escuta

Request

curl -X POST --header 'Accept: application/json' \
             --header 'Access-Token: seu-token' \
             -d '{"numero":"+5510999999999", "modo": 1}' \
             'https://voice-api.zenvia.com/chamada/123/escuta'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->chamada->escutar(123, '+5510999999999', 1);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.chamada.escutar(123, "+5510999999999", 1)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
response, err := client.Chamada.Escutar(123, "+5510999999999", 1)

from totalvoice.cliente import Cliente

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.chamada.escuta_chamada("123", '+5510999999999',"1")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Chamada chamada = new Chamada(client);
JSONObject response = chamada.escutar(123, "+5510999999999", 1);

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.chamada.escutar(123, "+5510999999999", 1)

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "escuta criada com sucesso"
}

Para realizar uma escuta para uma chamada que está ativa, basta informar o ID da mesma.

Método utilizado:

GET https://voice-api.zenvia.com/chamada/{id}/escuta

Veja ao lado um exemplo de requisição. Os campos são:

Request

id Obrigatório	ID da chamada a ser escutada
numero Obrigatório	Número do seu telefone
modo Obrigatório	Modo de Escuta 1 = escuta 2 = sussurro 3 = conferência

Transferir Chamadas

Definição

POST https://voice-api.zenvia.com/chamada/{id}/transfer

Request

curl -X POST --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' \
            -d '{"numero":"+5510999999999", "perna": "destino"}' \
            'https://voice-api.zenvia.com/chamada/123/transfer'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->chamada->transferir(123, '+5510999999999', 'destino');

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.chamada.transferir(123, "+5510999999999", "destino")
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
response, err := client.Chamada.Transferir(123, "+5510999999999", "destino")

from totalvoice.cliente import Cliente

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.chamada.transferir("123", "+5510999999999", "destino")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Chamada chamada = new Chamada(client);
JSONObject response = chamada.transferir(123, "+5510999999999", "destino");

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.chamada.transferir(123, "+5510999999999", "destino")

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "a chamada está sendo transferida"
}

Para transferir a origem ou destino para outro telefone e desconectar a outra perna (Beta), basta informar o ID da chamada.

Método utilizado:

POST https://voice-api.zenvia.com/chamada/{id}/transfer

Veja ao lado um exemplo de requisição. Os campos são:

Request

id Obrigatório	ID da chamada a ser transferida
numero Obrigatório	Número ao qual a chamada será transferida
perna Obrigatório	Qual perna da chamada será transferida? origem destino

Avaliar Chamadas

Definição

GET https://voice-api.zenvia.com/chamada/{id}/avaliar

Request

curl -X POST --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' \
            -d '{"numero":"5", "comentario": "muito boa"}' \
            'https://voice-api.zenvia.com/chamada/123/avaliar'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->chamada->avaliar(123, '5', 'muito boa');

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.chamada.avaliar(123, "5", "muito boa")
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
response, err := client.Chamada.Avaliar(123, "5", "muito boa")

from totalvoice.cliente import Cliente

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.chamada.avaliar("123", "5", "muito boa")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Chamada chamada = new Chamada(client);
JSONObject response = chamada.avaliar(123, "5", "muito boa");

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.chamada.avaliar(123, "5", "muito boa")

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "chamada avaliada com sucesso"
}

Para avaliar a chamada e obter estatísticas de qualidade de seus clientes, basta informar o ID da chamada.

Método utilizado:

GET https://voice-api.zenvia.com/chamada/{id}/avaliar

Veja ao lado um exemplo de requisição. Os campos são:

Request

id Obrigatório	ID da chamada a ser avaliada
nota Obrigatório	Nota de 1 a 5
comentario Obrigatório	Texto de até 1000 caracteres com a avaliação.

Conferências

Conferência Endpoint

https://voice-api.zenvia.com/conferencia

Usando esse recurso, você poderá criar salas privadas e receber um ID para ser utilizado ao realizar chamadas. Ao serem atendidas, estas chamadas se conectam com as conferências.

Objeto Conferências

JSON

{
    "id": 432,
    "data_criacao": "2016-03-27T15:12:44+03:00",
    "data_termino": "2016-03-27T15:12:49+03:00",
    "chamadas": [
          {
                  "id": 46132,
                  "conferencia_id" : 432,
                  "url_gravacao": "http://fooooo.bar/gravacao.mp3",
                  "numero": "+5510999999999",
                  "data_criacao": "2016-03-27T15:12:44+03:00",
                  "cli": 3132,
                  "duracao": "00:00:45",
                  "duracao_cobrada": "00:00:60",
                  "duracao_falada": "00:00:35",
                  "status": "atendida",
                  "preco": 0.12,
                  "data_inicio": "2016-03-27T15:13:11+01:00"                  
          }
    ]
}

O objeto é um modelo JSON que retorna a lista de chamadas da conferência.

Para realizar a chamada, é necessário que esta contenha os parâmetros solicitados abaixo na tabela Atributos. Ao final, a API fará o retorno.

Endpoint: https://voice-api.zenvia.com/conferencia

Atributos

id integer	Identificador único da conferência.
data_criacao datetime	Data e hora que foi criada a conferência.
data_termino datetime	Data e hora que a conferência foi fechada.
chamadas array	Lista de objetos de cada chamada da conferência.

Objeto Chamada da Conferência

JSON

{
    "id": 46132,
    "conferencia_id" : 432,
    "url_gravacao": "http://fooooo.bar/gravacao.mp3",
    "numero": "+5510999999999",
    "data_criacao": "2016-03-27T15:12:44+03:00",
    "cli": 3132,
    "duracao": "00:00:45",
    "duracao_cobrada": "00:00:60",
    "duracao_falada": "00:00:35",
    "status": "atendida",
    "preco": 0.12,
    "data_inicio": "2016-03-27T15:13:11+01:00"                  
}

O objeto é um modelo JSON. Para realizar a chamada, é necessário que esta contenha os parâmetros solicitados abaixo na tabela Atributos. Ao final, a API fará o retorno.

Endpoint: https://voice-api.zenvia.com/conferencia

Atributos

id integer	Identificador único da chamada da conferência.
conferencia_id id	Identificador único da conferência.
url_gravacao string	Endereço URL da gravação desta chamada na conferência.
numero integer	Número do destinatário que foi conectado à conferência.
data_criacao datetime	Data e hora que foi criada a chamada.
cli integer	Identificador único do cliente.
duracao datetime	Duração total da chamada desde o início do processamento.
duracao_cobrada datetime	Duração total da chamada considerada para fins de cobrança.
duracao_falada datetime	Duração da chamada desde que o destino atendeu.
status string	Estado atual da chamada.
preco float	Valor cobrado por esta chamada da conferência.
data_inicio datetime	Data do início da chamada.

Criar Conferência

Definição

POST https://voice-api.zenvia.com/conferencia

Request

curl -X POST --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: {{access-token}}' \
             -d '{"numero_destino":"+5510999999999","url_conferencia":"http://foo.bar/conferencia.mp3"}' \
             'https://voice-api.zenvia.com/conferencia'

<?php
$client = new TotalVoiceClient('seu-token');

$response = $client->conferencia->enviar('NUMERO-DESTINO', 'http://foo.bar/conferencia.mp3');

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.conferencia.enviar("+5510999999999", "http://foo.bar/conferencia.mp3")
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.Conferencia.Enviar("+5510999999999", "http://foo.bar/conferencia.mp3", false, "")

from totalvoice.cliente import Cliente

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.conferencia.cria_conferencia()

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Conferencia conferencia = new Conferencia(client);

JSONObject response = conferencia.enviar("+5510999999999", "http://foo.bar/conferencia.mp3");

Response

{
    "status": 200,
    "sucesso": true,
    "motivo": 0,
    "mensagem": "conferencia criado com sucesso",
    "dados": {
        "id": 4921
    }
}

Para criar uma conferência, basta chamar o método cria_conferencia para criar o id da mesma.

POST: https://voice-api.zenvia.com/conferencia

REQUEST:

• Headers

1. Content-Type: application/json
2. Authorization: Access-Token: {{access-token}}

Veja ao lado um exemplo de requisição. No campo ID, o response retorna o ID da conferência.

Response

id integer

Retorna o ID do Conferência

Buscar Conferência

Definição

GET https://voice-api.zenvia.com/conferencia/{id}

Request

curl -X GET --header 'Content-Type: application/json' \
            --header 'Accept: application/json' \
            --header 'Access-Token: {{access-token}}' 'https://voice-api.zenvia.com/conferencia/1'

<?php
$client = new TotalVoiceClient('seu-token');

$response = $client->conferencia->buscaConferencia(123);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.conferencia.buscar(123)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.Conferencia.Buscar(123)

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.conferencia.get_by_id(123)

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Conferencia conferencia = new Conferencia(client);

JSONObject response = conferencia.buscar(123);

Response

{
    "status": 200,
    "sucesso": true,
    "motivo": 0,
    "mensagem": "dados retornados com sucesso",
    "dados": {
        "id": 432,
        "numero_destino": "+5510999999999",
        "data_criacao": "2016-03-27T15:12:44+03:00",
        "data_inicio": "2016-03-27T15:12:49+03:00",
        "tipo": "fixo",
        "status": "atendida",
        "duracao_segundos": 45,
        "duracao": "00:00:45",
        "duracao_cobrada_segundos": 60,
        "duracao_cobrada": "00:00:60",
        "duracao_falada_segundos": 35,
        "duracao_falada": "00:00:35",
        "preco": 0.12,
        "url_conferencia": "http://fooooo.bar/conferencia.mp3",
        "resposta_usuario": true,
        "resposta": "8"
    }
}

Caso deseje, após o envio de mensagens de conferência, você poderá realizar a busca do registro pelo seu ID.

Para buscar, é necessário o envio da chave da fila na URL da requisição seguido da autenticação Acess Token no Header.

A chamada para obter os dados da consulta deve ser realizada utilizando um HTTP GET para o endereço de definição da API.

GET https://voice-api.zenvia.com/conferencia/{id}

Request

ID Obrigatório

ID da Conferência para recuperar os dados

Response

dados object

Retorna o objeto conferência

Encerrar Conferência

Para encerrar uma conferência, basta informar o período desejado e, por parâmetro, o ID da conferência que deseja encerrar.

Método utilizado:

DELETE https://voice-api.zenvia.com/conferencia/{id}

Relatório Conferência

Definição

GET https://voice-api.zenvia.com/conferencia/relatorio

Request

curl -X GET --header 'Accept: application/json' \
            --header 'Access-Token: {{access-token}}' \
            'https://voice-api.zenvia.com/conferencia/relatorio?data_inicio=2018-03-14&data_fim=2018-03-15'

<?php
$client = new TotalVoiceClient('seu-token');

$response = $client->conferencia->relatorio($dataInicial, $dataFinal);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.conferencia.relatorio(data_inicial, data_final)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.Conferencia.Relatorio.Gerar(dataInicial, dataFinal)

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.conferencia.get_relatorio(data_inicio, data_fim)

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Conferencia conferencia = new Conferencia(client);

JSONObject response = conferencia.relatorio(dataInicial, dataFinal);

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "relatorio": [
      {
        "id": 432,
        "numero_destino": "+5510999999999",
        "data_criacao": "2016-03-27T15:12:44+03:00",
        "data_inicio": "2016-03-27T15:12:49+03:00",
        "tipo": "fixo",
        "status": "atendida",
        "duracao_segundos": 45,
        "duracao": "00:00:45",
        "duracao_cobrada_segundos": 60,
        "duracao_cobrada": "00:00:60",
        "duracao_falada_segundos": 35,
        "duracao_falada": "00:00:35",
        "preco": 0.12,
        "url_conferencia": "http://fooooo.bar/conferencia.mp3",
        "resposta_usuario": true,
        "resposta": "8"
      },
      {
        "id": 432,
        "numero_destino": "+5510999999999",
        "data_criacao": "2016-03-27T15:12:44+03:00",
        "data_inicio": "2016-03-27T15:12:49+03:00",
        "tipo": "fixo",
        "status": "ocupado",
        "duracao_segundos": 10,
        "duracao": "00:00:10",
        "duracao_cobrada_segundos": null,
        "duracao_cobrada": null,
        "duracao_falada_segundos": null,
        "duracao_falada": null,
        "preco": 0,
        "url_conferencia": "http://fooooo.bar/conferencia.mp3",
        "resposta_usuario": true,
        "resposta": null
      }
    ]
  }
}

Para consultar as conferências, basta informar o período desejado para que a API retorne os dados.

Veja ao lado um exemplo de requisição. Os campos são:

Request

data_inicio Obrigatório Query String	Data inicial para consulta dos dados no relatório
data_fim Obrigatório Query String	Data final para consulta dos dados no relatório
posicao Opcional Query String	Posição para seleção dos dados do relatório - começa na posição 0. Também chamado de offset.
limite Opcional Query String	Quantidade de chamadas a retornar na consulta. O limite padrão é 100 e o máximo é 200.

Response

relatorio array

Retorna um array com objetos conferência

Webphone

Webphone End Point

https://voice-api.zenvia.com/webphone

Webphone é uma maneira de se conectar a um Ramal diretamente por um computador. Todo ramal tem uma URL pela qual é possível acessar o Webphone sem precisar se conectar à plataforma da ZenAPI.

Ele é muito utilizado em integrações para implementar ligações diretamente em um software ou sistema de uma maneira fácil.

Há três tipos de Webphone:

1. Floating: quando você vai abrir o Webphone em um popup;
2. Embedded: se o Webphone ficará embutido no site / sistema;
3. Hidden: sem interface, apenas funções Javascript.

Um webphone é vinculado diretamente a um Ramal.

Consultar URL Webphone

Definição

GET https://voice-api.zenvia.com/webphone

Para consultar a URL do Webphone de um determinado Ramal, basta enviar os parâmetros para pré-configuração do webphone.

A URL gerada vem com um código único para acesso daquele Webphone, sem ser necessário login na plataforma da ZenAPI.

Request

curl 'https://voice-api.zenvia.com/webphone?ramal=4000' \
    -X GET \
    --header 'Access-Token: Seu_Token'

<?php
$client = new TotalVoiceClient('Seu_Token');

$webphone_dados = array("ramal" => 4000);
$response = $client->central->webphone($webphone_dados);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("Seu_Token");

var webphone_dados = { 
    ramal: 4000
};
client.central.webphone(webphone_dados)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("Seu_Token")

m := map[interface{}]interface{}{}
m["ramal"] = 4000

response, err := client.Ramal.Webphone(m)

client = Cliente("Seu_Token", 'voice-api.zenvia.com')
response = client.webphone.get_webphone("floating", None, 4000)

TotalVoiceClient client = new TotalVoiceClient("Seu_Token");
Central central = new Central(client);

JSONObject webphone_dados = new JSONObject();
webphone_dados.put("ramal", 4000);

JSONObject response = central.webphone(webphone_dados);

Response

{
    "status": 200,
    "sucesso": true,
    "motivo": 0,
    "mensagem": "url webphone",
    "dados": {
        "url": "https://voice-api.zenvia.com/w3/?key=XXXXXXXXXXXXXXXXXXXXXX83b3420&pop=1"
    }
}

Request Query

id_ramal Opcional	Identificador único do Ramal que você deseja usar no Webphone, obrigatório caso não for informar o campo ramal.
ramal Opcional	Número do Ramal que você deseja buscar o Webphone, obrigatório caso não for informar o campo id_ramal.
ligar_para Opcional	Se você deseja que o Webphone já disque automaticamente para algum número quando abrir, deverá informar o número neste campo.
fechar_fim Opcional	Se você quiser que o Webphone feche ao fim da ligação deve colocar esse campo como true;
tipo Opcional	Tipo do Webphone, poderá ser: floating, embedded, hidden, por padrão irá o Floating.

Response

url string

Retorna a URL completa do Webphone do Ramal desejado.

Criar Webphone

Para criar um webphone, utilize nosso exemplo localizado em Exemplo Webphone.

Funções do Webphone

function conectar(){
                webphone.contentWindow.postMessage({message : 'conectar'}, '*');
            }

function desconectar(){
                webphone.contentWindow.postMessage({message : 'desconectar'}, '*');
            }

function chamaNumero(numero) {
                webphone.contentWindow.postMessage({
                    message: 'chamaNumero',
                    'numero': numero
                }, '*');
            }

function atender() {
                webphone.contentWindow.postMessage({
                    message: 'answer'
                }, '*');
            }

function desligaChamada() {
                webphone.contentWindow.postMessage({
                    message: 'hangup'
                }, '*');
            }

function enviaDTMF(meuDTMF) {
                webphone.contentWindow.postMessage({
                    message: 'enviaDTMF',
                    'dtmf': meuDTMF
                }, '*');
            }

function mute() {
                webphone.contentWindow.postMessage({
                    message: 'mute'
                }, '*');
            }

function transferir(numeroTelefone) {
                webphone.contentWindow.postMessage({
                    message: 'transferir',
                    'numeroTelefone': numeroTelefone
                }, '*');
            }

function transferirConsulta(numeroTelefone) {
                webphone.contentWindow.postMessage({
                    message: 'transferirConsulta',
                    'numeroTelefone': numeroTelefone
                }, '*');
            }

function recstart() {
                webphone.contentWindow.postMessage({
                    message: 'recStart'
                }, '*');
            }

function recstop() {
                webphone.contentWindow.postMessage({
                    message: 'recStop'
                }, '*');                
            }

function pausarNaFila(filaId) {
                webphone.contentWindow.postMessage({
                message: 'pausarNaFila',
                filaId: filaId
                }, '*');
            }

function despausarNaFila(filaId) {
                webphone.contentWindow.postMessage({
                message: 'despausarNaFila',
                filaId: filaId
                }, '*');
            }

function entrarNaFila(filaId) {
                webphone.contentWindow.postMessage({
                message: 'entrarNaFila',
                filaId: filaId
                }, '*');
            }

function sairDaFila(filaId) {
                webphone.contentWindow.postMessage({
                message: 'sairDaFila',
                filaId: filaId
                }, '*');
            }

conectar()	Conecta o webphone
desconectar()	Desconecta o webphone
chamaNumero(numero)	Telefona para o número/ramal destino
atender()	Atender chamada
desligaChamada()	Encerra chamada ativa
enviaDTMF(meuDTMF)	Envia um DTMF(número ou caracter) através de uma tecla. Números de 0 à 9, Asterisco(*) ou Sustenido(#).
mute()	Microfone fica mudo
transferir(numeroTelefone)	Transferir ligação sem consulta
transferirConsulta(numeroTelefone)	Transferir ligação com consulta
recstart()	Inicia a gravação parcial de uma chamada
recstop()	Encerra a gravação parcial da chamada
pausarNaFila(filaId)	Pausa um ramal na fila `filaId` ou em todas as filas caso nenhum valor seja passado
despausarNaFila(filaId)	Despausa um ramal na fila `filaId` ou em todas as filas caso nenhum valor seja passado
entrarNaFila(filaId)	Insere o ramal na fila definida em `filaId`
sairDaFila(filaId)	Remove o ramal na fila definida em `filaId`

Eventos do Webphone

Caso queira adicionar um evento, veja abaixo na tabela a lista de todos os disponíveis e, ao lado, o exemplo de requisições.

if (e.data.message == 'chegandoChamada') {
    alert('Chegando Chamada de ' + e.data.numeroChegando + ' para: ' + 
    e.data.numeroDestino + ' chamada_recebida_id: ' + e.data.chamadaRecebidaId);
}


if (e.data.message == 'status') {
    alert('Status: ' + e.data.status);
}


if (e.data.message == 'chamada_id') {
    alert('Chamada_id: ' + e.data.chamada_id);
}


if (e.data.message == 'status_erro') {
    alert('Sem Permissão: ' + e.data.status_erro);
}


if (e.data.message == 'stats_webphone') {
    alert('Internet: ' + e.data.internet + ' e computador: ' + e.data.computador);
}

if (e.data.message == 'entrou_na_fila') {
    alert('Ramal entrou na fila');
}

if (e.data.message == 'saiu_da_fila') {
    alert('Ramal saiu da fila');
}

if (e.data.message == 'pausou_na_fila') {
    alert('Ramal foi pausado na fila');
}

if (e.data.message == 'despausou_na_fila') {
    alert('Ramal foi despausado na fila');
}

chegandoChamada	Ao receber uma chamada é disparado uma mensagem com o número de envio(e.data.numeroChegando), número de destino(e.data.numeroDestino) e o ID da chamada( e.data.chamadaRecebidaId).
status	Dispara uma mensagem ao ser alterado o status da chamada(e.data.status), que são exemplos de status: conectado, desconectado, chamando, encerrada, conversando.
chamada_id	Ao ser iniciada a chamada é disparado esse evento que retorna o identificador único da chamada(e.data.chamada_id), o ID é único e pode ser utilizado na api para recuperação de mais informações (get na api ou webhooks).
status_erro	Ao ocorrer um erro(e.data.status_erro) durante a efetuação da chamada é disparado esse evento.
stats_webphone	Recebe o status da qualidade de conexão(Diagnóstico do Ping e Jitter) e computador(Uso da CPU) para verificar a qualidade da ligação.
pausou_na_fila	É chamado quando o ramal é pausado em alguma fila.
despausou_na_fila	É chamado quando o ramal é despausado em alguma fila.
entrou_na_fila	É chamado quando o ramal entra em alguma fila.
saiu_da_fila	É chamado quando o ramal sai de alguma fila.

APIs de Torpedos

AS APIs de Torpedo viabilizam a entrega de mensagens para os clientes. Nossa documentação possui as amostras de código para você iniciar o disparo de mensagens com leitura de texto TTS e envios de torpedo de voz.

APIs de Torpedo:

• Áudio
• Composto
• TTS: leitura de texto

Áudio

Áudio Endpoint

https://voice-api.zenvia.com/audio

Usando esse recurso, você pode enviar um torpedo de voz ou mensagens de voz como áudio para o destino através de um arquivo MP3. Poderá também enviar algumas opções adicionais. São elas:

• Aguardar uma resposta do usuário;
• Gravar o áudio da ligação;
• Colocar um número bina que aparecerá no momento da ligação.

Observações:

1. Os arquivos de áudio devem estar disponíveis em uma URL pública direcionando para um arquivo de áudio MP3.
2. O tamanho máximo é de 5MB.
3. O formato de envio no campo numero_destino é DDD + número. (Ex. p/ SP: 11912341234).

Objeto Áudio

JSON

{
    "id": 12345678,
    "numero_destino": "+5510999999999",
    "data_criacao": "2019-05-22T09:18:44.000-03:00",
    "data_inicio": "2019-05-22T09:18:44.000-03:00",
    "tipo": "movel",
    "status": "atendida",
    "duracao_segundos": 22,
    "duracao": "00:00:22",
    "duracao_cobrada_segundos": 60,
    "duracao_cobrada": "00:01:00",
    "duracao_falada_segundos": 2,
    "duracao_falada": "00:00:02",
    "preco": 0.36,
    "url_audio": "https://sua.url.audio/files/audios/audio.mp3",
    "resposta_usuario": true,
    "resposta": "1",
    "motivo_desconexao": null,
    "url_gravacao": "https://voice-api.zenvia.com/rec/123456789",
    "bina": "+5510888888888"
}

O objeto é um modelo JSON que contém o arquivo de áudio.

Para realizar a chamada, é necessário que esta contenha os parâmetros solicitados abaixo na tabela Atributos. Ao final, a API fará o retorno.

Endpoint: https://voice-api.zenvia.com/audio

No atributo “status”, os seguintes valores podem ser retornados:

• Preparando
• Chamando
• Atendida
• Ocupado
• Sem resposta
• Congestionado
• Falha
• Cancelada
• Desconhecido

Atributos

id integer	ID do registro de Áudio.
numero_destino string	Número do destinatário que foi enviado o áudio.
data_criacao datetime	Data e hora que foi criado o registro.
data_inicio datetime	Data e hora que foi iniciado o processamento do áudio.
tipo string	Tipo de telefone: fixo, móvel ou ramal.
status string	Status do registro.
duracao_segundos integer	Duração em total em segundos, da chamada, desde o início do processamento.
duracao String	Duração total da chamada desde o início do processamento
duracao_cobrada_segundos integer	Duração em segundos para fins de cobrança.
duracao_cobrada String	Duração considerada para fins de cobrança.
duracao_falada_segundos integer	Duração em segundos da chamada desde que o destino atendeu.
duracao_falada String	Duração da chamada desde que o destino atendeu.
preco float	Valor cobrado pela chamada.
url_audio string	URL do Áudio enviado para a chamada.
resposta_usuario boolean	Valor enviado identendificando se aceita a resposta do usuário.¹
resposta string	Se você enviou resposta_usuario = true, quando o usuário executa alguma ação no teclado númerico do dispositivo, o valor será exibido neste campo (DTMF).¹
motivo_desconexao string	Aqui é informado o motivo do derrubamento da ligação, você pode ver mais em motivos de desconexão
url_gravacao string	Quando enviado a opção Gravar Áudio = true, este campo disponibilizará uma URL contendo o áudio da gravação da ligação.
bina string	Número de telefone que aparece no identificador de quem recebe a chamada

Criar Áudio

Definição

POST https://voice-api.zenvia.com/audio

Request

curl -X POST --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: seu-token' \
             -d '{"numero_destino":"+5510999999999", "bina": "+5510888888888" ,"url_audio":"http://sua.url.audio/audio.mp3"}' \
             'https://voice-api.zenvia.com/audio'

<?php
require_once "vendor/autoload.php";
use TotalVoice\Client as TotalVoiceClient;

$client = new TotalVoiceClient('seu-token');
$response = $client->audio->enviar('+5510888888888', 'http://sua.url.audio/audio.mp3');

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.audio.enviar("+5510999999999", "http://sua.url.audio/audio.mp3")
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.Audio.Enviar("+5510999999999", "http://sua.url.audio/audio.mp3", false, "")

from totalvoice.cliente import Cliente

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.audio.enviar("+5510999999999", "http://sua.url.audio/audio.mp3")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Audio audio = new Audio(client);

JSONObject response = audio.enviar("+5510999999999", "http://sua.url.audio/audio.mp3");

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.audio.enviar("+5510999999999", "http://sua.url.audio/audio.mp3")

Response

{
    "status": 200,
    "sucesso": true,
    "motivo": 0,
    "mensagem": "audio criado com sucesso",
    "dados": {
        "id": 4921
    }
}

Para criar um áudio, basta informar o número de destino válido e a URL pública do arquivo.

POST: https://voice-api.zenvia.com/audio

REQUEST:

• Headers

1. Content-Type: application/json
2. Authorization: Access-Token: seu-token

Veja ao lado um exemplo de requisição. Os campos são:

Request

numero_destino Obrigatório	Número do telefone que irá receber a chamada, formato E.164: [+][DDI][DDD][Número], exemplo: +5510999999999.
url_audio Obrigatório	URL do áudio, exemplo: http://sua.url.audio/audio.mp3.
resposta_usuario Opcional	Aguardar uma resposta do destinário.
gravar_audio Opcional	Gravar a ligação.
bina Opcional	Número de telefone que aparecerá no identificador de quem receber a chamada, formato E.164: [+][DDI][DDD][Número], exemplo: +5510999999999.
detecta_caixa Opcional	Caso identificado caixa, a ligação será derrubada antes que a ligação seja atendida. Esse serviço tem um custo adicional.
bina_inteligente Opcional	Quando o valor for true, ao enviar o torpedo o número de telefone que aparecerá para o destino será um número com DDD de sua região. Veja DDDs disponíveis.

Buscar Áudio

Definição

GET https://voice-api.zenvia.com/audio/{id}

Request

curl -X GET --header 'Content-Type: application/json' \
            --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' 'https://voice-api.zenvia.com/audio/ID-Audio'

<?php
require_once "vendor/autoload.php";
use TotalVoice\Client as TotalVoiceClient;

$client = new TotalVoiceClient('seu-token');
$response = $client->audio->buscaAudio(id-audio);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.audio.buscar(123)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.Audio.Buscar(123)

from totalvoice.cliente import Cliente

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.audio.get_by_id("123")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Audio audio = new Audio(client);

JSONObject response = audio.buscar(123);

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.audio.enviar("NUMERO-DESTINO", "URL-AUDIO")

Response

{
    "status": 200,
    "sucesso": true,
    "motivo": 0,
    "mensagem": "dados retornados com sucesso",
    "dados": {
        "id": 432,
        "numero_destino": "+5510999999999",
        "data_criacao": "2016-03-27T15:12:44+03:00",
        "data_inicio": "2016-03-27T15:12:49+03:00",
        "tipo": "fixo",
        "status": "atendida",
        "duracao_segundos": 45,
        "duracao": "00:00:45",
        "duracao_cobrada_segundos": 60,
        "duracao_cobrada": "00:00:60",
        "duracao_falada_segundos": 35,
        "duracao_falada": "00:00:35",
        "preco": 0.12,
        "url_audio": "http://fooooo.bar/audio.mp3",
        "resposta_usuario": true,
        "resposta": "8",
        "motivo_desconexao": null,
        "url_gravacao": "",
        "bina": "+5510888888888"
    }
}

Caso deseje, após o envio de mensagens de áudio você poderá realizar a busca do registro pelo seu ID.

Para buscar, é necessário o envio da chave do áudio na URL da requisição seguido da autenticação Acess Token no Header.

A chamada para obter os dados da consulta deve ser realizada utilizando um HTTP GET para o endereço de definição da API.

GET https://voice-api.zenvia.com/audio/{id}

Request

id Obrigatório

ID do Áudio para recuperar os dados

Response

dados object

Retorna o objeto áudio

Relátorio Áudio

Definição

GET https://voice-api.zenvia.com/audio/relatorio

Request

curl -X GET --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' \
            'https://voice-api.zenvia.com/audio/relatorio?data_inicio=2018-03-14&data_fim=2018-03-15'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->audio->relatorio($dataInicial, $dataFinal);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.audio.relatorio(data_inicial, data_final)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.Audio.Relatorio.Gerar(dataInicial, dataFinal)

from totalvoice.cliente import Cliente


client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.audio.get_relatorio("2017-12-08T11:00:32-02:00", "2017-12-08T11:00:32-02:00")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Audio audio = new Audio(client);

JSONObject response = audio.relatorio(dataInicial, dataFinal);

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.audio.enviar("NUMERO-DESTINO", "URL-AUDIO")

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "relatorio": [
      {
        "id": 432,
        "numero_destino": "+5510999999999",
        "data_criacao": "2016-03-27T15:12:44+03:00",
        "data_inicio": "2016-03-27T15:12:49+03:00",
        "tipo": "fixo",
        "status": "atendida",
        "duracao_segundos": 45,
        "duracao": "00:00:45",
        "duracao_cobrada_segundos": 60,
        "duracao_cobrada": "00:00:60",
        "duracao_falada_segundos": 35,
        "duracao_falada": "00:00:35",
        "preco": 0.12,
        "url_audio": "http://fooooo.bar/audio.mp3",
        "resposta_usuario": true,
        "resposta": "8",
        "motivo_desconexao": null,
        "url_gravacao": "",
        "bina": "+5510888888888"
      },
      {
        "id": 432,
        "numero_destino": "+5510999999999",
        "data_criacao": "2016-03-27T15:12:44+03:00",
        "data_inicio": "2016-03-27T15:12:49+03:00",
        "tipo": "fixo",
        "status": "ocupado",
        "duracao_segundos": 10,
        "duracao": "00:00:10",
        "duracao_cobrada_segundos": null,
        "duracao_cobrada": null,
        "duracao_falada_segundos": null,
        "duracao_falada": null,
        "preco": 0,
        "url_audio": "http://fooooo.bar/audio.mp3",
        "resposta_usuario": true,
        "resposta": "",
        "motivo_desconexao": null,
        "url_gravacao": "",
        "bina": "+5510888888888"
      }
    ]
  }
}

Para consultar os áudios enviados, basta informar o período desejado para que a API retorne os dados.

Veja ao lado um exemplo de requisição. Os campos são:

Request

data_inicio Obrigatório Query String	Data inicial para consulta dos dados no relatório.
data_fim Obrigatório Query String	Data final para consulta dos dados no relatório.
posicao Opcional Query String	Posição para seleção dos dados do relatório - começa na posição 0. Também chamado de offset.
limite Opcional Query String	Quantidade de chamadas a retornar na consulta. O limite padrão é 100 e o máximo é 200.

Response

relatorio array

Retorna um array com objetos áudio

Composto

Composto Endpoint

https://voice-api.zenvia.com/composto

[
    {
        "acao": "audio",
        "acao_dados": {
                        "url_audio": "http://fooooo.bar/composto.mp3"
                    }
    },
    {
        "acao": "tts",
        "acao_dados": {
                        "mensagem": "Você possui uma consulta agendada para amanhã 18h. Aperte 1 para confirmar ou 2 para ser remarcar",
                        "resposta_usuario": "true",
                        "tipo_voz": "br-Ricardo"
                    }
    },
    {
        "acao": "transferir",
        "opcao": 2,
        "acao_dados": {
                        "numero_telefone": "+5510999999999",
                         "bina": "+5510888888888" 
                    }
    } 
]

Usando esse recurso, você poderá enviar mensagens de voz por telefone misturando gravações de áudio MP3 com TTS. Além disso, será possível também realizar outras funções de central telefônica, como coletar e transferir DTMF.

Por exemplo: envie uma mensagem para confirmar uma consulta ou transferir a pessoa para o reagendamento: "Você possui uma consulta agendada para amanhã às 18h. Pressione 1 para confirmar ou 2 para ser remarcado". Quando o usuário pressionar a opção 2, será transferido para o telefone de remarcação.

O composto aceita um JSON com as seguintes opções:

• Áudio;
• TTS;
• Transferir;
• URA;

Observações:

• Os arquivos de áudio são aceitos nos formatos MP3;
• O tamanho máximo é de 5MB.

Objeto Composto

JSON

{
    "id": 432,
    "numero_destino": "+5510999999999",
    "data_criacao": "2016-03-27T15:12:44+03:00",
    "data_inicio": "2016-03-27T15:12:49+03:00",
    "tipo": "fixo",
    "status": "atendida",
    "duracao_segundos": 45,
    "duracao": "00:00:45",
    "duracao_cobrada_segundos": 60,
    "duracao_cobrada": "00:00:60",
    "duracao_falada_segundos": 35,
    "duracao_falada": "00:00:35",
    "preco": 0.12,
    "resposta_usuario": true,
    "resposta": "8",
    "tags": "clienteX",
    "url_gravacao": "http://fooooo.bar/gravacao.mp3",
    "bina": "+5510888888888"
}

O objeto é um modelo JSON que contém o arquivo de composto.

Para realizar a chamada, é necessário que esta contenha os parâmetros solicitados abaixo na tabela Atributos. Ao final, a API fará o retorno.

Endpoint: https://voice-api.zenvia.com/composto

No atributo “status”, os seguintes valores podem ser retornados:

• Preparando
• Chamando
• Atendida
• Ocupado
• Sem resposta
• Congestionado
• Falha
• Cancelada
• Desconhecido

Atributos

id integer	ID do registro de Áudio.
numero_destino string	Número do destinatário que foi enviado o áudio.
data_criacao datetime	Data e hora que foi criado o registro
data_inicio datetime	Data e hora que foi iniciado o processamento do áudio
tipo string	Tipo de telefone: fixo, móvel ou ramal
status string	Status do registro
duracao_segundos integer	Duração em segundos (inteiro) do total da chamada desde o início do processamento
duracao integer	Duração total da chamada desde o início do processamento
duracao_cobrada_segundos integer	Duração em segundos para fins de cobrança
duracao_cobrada integer	Duração considerada para fins de cobrança
duracao_falada_segundos integer	Duração em segundos da chamada desde que o destino atendeu
duracao_falada integer	Duração da chamada desde que o destino atendeu
preco float	Valor cobrado pela chamada
resposta_usuario boolean	Aguarda a resposta do usuário: sim ou não
resposta string	Quando o usuário executa alguma ação no teclado do dispositivo, o valor será exibido neste campo (DTMF).
url_gravacao string	Quando enviado a opção Gravar Áudio = true, este campo disponibilizará uma URL contendo o áudio da gravação da ligação.
tags string	Parâmetro de integração - informado no post e retornado no get. Ex: "clienteX"
motivo_desconexao string	Um dos motivos de desconexão: 1. telefone não existe 2. sem rota para a rede de destino 3. sem rota para o destino 4. prefixo incorreto 6. canal inaceitável 7. chamada sendo entregue em canal já estabelecido 8. call peemption 14. telefone portado para outra operadora 16. normal 17. ocupado 18. sem resposta 19. sem resposta - mas chamou 20. assinante ausente 21. chamada rejeitada 22. este número mudou 23. redirecionado para novo destino 26. atendido em outro lugar 27. destino não está funcionando 28. formato inválido de número 29. rejeitado 30. resposta para status enquiry 31. normal, não especificado 34. sem canal disponível 41. falha temporária 42. equipamento congestionado 44. canal requisitado não está disponível 50. não cadastrado 52. chamada sainte barrada 54. chamada entrante barrada 57. capacidade não autorizada 58. erro de mídia ou parâmetros incompatíveis 65. capacidade do portador não implementada 66. tipo de canal não implementado 69. não implementado 81. valor de referência inválido 88. destino incompatível 95. mensagem inválida não especificada 96. informação obrigatória não presente 97. mensagem não implementada 98. mensagem não compatível com o estado da chamada ou não existente ou não implementada 97. mensagem não implementada 99. elemento não existente ou não implementado 97. mensagem não implementada 100. informação inválida no conteúdo dos elementos 101. mensagem não compatível com o estado da chamada 102. timeout 111. erro de protocolo 127. erro de conectividade
bina string	Número de telefone que aparece no identificador de quem recebe a chamada

Criar Composto

Definição

POST https://voice-api.zenvia.com/composto

Request

curl -X POST --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: seu-token' \
             -d '{
                "numero_destino":"+5510999999999",
                "bina": "+5510888888888",
                "dados":[
                    {  
                        "acao":"audio",
                        "acao_dados":{  
                            "url_audio":"https://instaud.io/_/3K3k.mp3"
                        }
                    },
                    {  
                        "acao":"tts",
                        "acao_dados":{  
                            "mensagem":"lendo este texto",
                            "resposta_usuario":"true",
                            "tipo_voz":"br-Ricardo"
                        }
                    },
                    {  
                        "acao":"transferir",
                        "opcao":1,
                        "acao_dados":{  
                            "numero_telefone":"+5510999999999",
                            "bina":"+5510888888888"
                        }
                    },
                        {  
                        "acao":"ura",
                        "opcao":2,
                        "acao_dados":{  
                            "ura_id":"1234"
                        }
                    }' \
             'https://voice-api.zenvia.com/composto'

<?php
$client = new TotalVoiceClient('seu-token');

$dados  = '[{"acao":"audio","acao_dados":{"url_audio":"http://fooooo.bar/composto.mp3"}},{"acao":"tts","acao_dados":{"mensagem":"lendo este texto","resposta_usuario":"true","tipo_voz":"br-Ricardo"}},{"acao":"transferir","opcao":1,"acao_dados":{"numero_telefone":"+5510999999999","bina":"+5510888888888"}}]';
$bina   = '11987654321';
$tags   = 'clienteY';

$response = $client->composto->enviar('NUMERO-DESTINO', $dados, $bina, $tags);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.composto.enviar("NUMERO-DESTINO", '[{"acao":"audio","acao_dados":{"url_audio":"http://fooooo.bar/composto.mp3"}},{"acao":"tts","acao_dados":{"mensagem":"lendo este texto","resposta_usuario":"true","tipo_voz":"br-Ricardo"}},{"acao":"transferir","opcao":1,"acao_dados":{"numero_telefone":"+5510999999999","bina":"+5510888888888"}}]','11987654321' , 'tags')
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.Composto.Enviar("NUMERO-DESTINO", '[{"acao":"audio","acao_dados":{"url_audio":"http://fooooo.bar/composto.mp3"}},{"acao":"tts","acao_dados":{"mensagem":"lendo este texto","resposta_usuario":"true","tipo_voz":"br-Ricardo"}},{"acao":"transferir","opcao":1,"acao_dados":{"numero_telefone":"+5510999999999","bina":"+5510888888888"}}]','11987654321' , 'tags')

from totalvoice.cliente import Cliente

client = Cliente("seu-token", 'voice-api.zenvia.com')
dados =[  
   {  
      "acao":"audio",
      "acao_dados":{  
         "url_audio":"https://instaud.io/_/3K3k.mp3"
      }
   },
   {  
      "acao":"tts",
      "acao_dados":{  
         "mensagem":"lendo este texto",
         "resposta_usuario":"true",
         "tipo_voz":"br-Ricardo"
      }
   },
   {  
      "acao":"transferir",
      "opcao":1,
      "acao_dados":{  
         "numero_telefone":"+5510999999999",
         "bina":"+5510888888888"
      }
   },
    {  
      "acao":"ura",
      "opcao":2,
      "acao_dados":{  
         "ura_id":"1234"
      }
   }
]
response = client.composto.enviar("NUMERO-DESTINO", dados ,'BINA' , 'TAGS')

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Composto composto = new Composto(client);

JSONObject response = composto.enviar("NUMERO-DESTINO", '[{"acao":"audio","acao_dados":{"url_audio":"http://fooooo.bar/composto.mp3"}},{"acao":"tts","acao_dados":{"mensagem":"lendo este texto","resposta_usuario":"true","tipo_voz":"br-Ricardo"}},{"acao":"transferir","opcao":1,"acao_dados":{"numero_telefone":"+5510999999999","bina":"+5510888888888"}}]','11987654321' , 'tags');

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.composto.enviar("NUMERO-DESTINO", '[{"acao":"audio","acao_dados":{"url_audio":"http://fooooo.bar/composto.mp3"}},{"acao":"tts","acao_dados":{"mensagem":"lendo este texto","resposta_usuario":"true","tipo_voz":"br-Ricardo"}},{"acao":"transferir","opcao":1,"acao_dados":{"numero_telefone":"+5510999999999","bina":"+5510888888888"}}]','11987654321' , 'tags')

Response

{
    "status": 200,
    "sucesso": true,
    "motivo": 0,
    "mensagem": "composto criado com sucesso",
    "dados": {
        "id": 4921
    }
}

Para criar um Composto, basta informar o número de destino válido e um JSON com o composto.

POST: https://voice-api.zenvia.com/composto

REQUEST:

• Headers
• Content-Type: application/json
• Authorization: Access-Token: seu-token

Veja ao lado um exemplo de requisição. Os campos são:

Request

numero_destino Obrigatório	Número do telefone que irá receber a chamada, formato E.164: [+][DDI][DDD][Número] exemplo: +5510999999999
dados Obrigatório	Objeto JSON com a estrutura de TTS, áudio, transferir e URA ¹
resposta_usuario Opcional	Aguardar uma resposta do destinatário
gravar_audio Opcional	Gravar a ligação
bina Opcional	Número de telefone que aparecerá no identificador de quem receber a chamada, formato E.164: [+][DDI][DDD][Número] exemplo: +5510999999999
tags Opcional	Campo de texto que será atrelado à ligação e devolvido no momento da consulta. Ex.: "clienteY"
bina_inteligente Opcional	Quando o valor for true, ao enviar o torpedo o número de telefone que aparecerá para o destino será um número com DDD de sua região. Veja DDDs disponíveis.

Response

id integer

Retorna o ID do Composto

Buscar Composto

Definição

GET https://voice-api.zenvia.com/composto/{id}

Request

curl -X GET --header 'Content-Type: application/json' \
            --header 'Accept: application/json' \
            --header 'Access-Token: {{access-token}}' 'https://voice-api.zenvia.com/composto/1'

<?php
$client = new TotalVoiceClient('seu-token');

$response = $client->composto->buscaCompost(123);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.composto.buscar(123)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.Composo.Buscar(123)

from totalvoice.cliente import Cliente

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.composto.get_by_id("123")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Composto composto = new Composto(client);

JSONObject response = composto.buscar(123);

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("{{access-token}}")
puts @client.composto.enviar("NUMERO-DESTINO", "URL-AUDIO")

Response

{
    "status": 200,
    "sucesso": true,
    "motivo": 0,
    "mensagem": "dados retornados com sucesso",
    "dados": {
        "id": 432,
        "numero_destino": "+5510999999999",
        "data_criacao": "2016-03-27T15:12:44+03:00",
        "data_inicio": "2016-03-27T15:12:49+03:00",
        "tipo": "fixo",
        "status": "atendida",
        "duracao_segundos": 45,
        "duracao": "00:00:45",
        "duracao_cobrada_segundos": 60,
        "duracao_cobrada": "00:00:60",
        "duracao_falada_segundos": 35,
        "duracao_falada": "00:00:35",
        "preco": 0.12,
        "resposta_usuario": true,
        "resposta": "8",
        "tags": "clienteX",
        "url_gravacao": "http://fooooo.bar/gravacao.mp3",
        "bina": "+5510888888888"
    }
}

Caso deseje, após o envio de mensagens composto, você poderá realizar a busca do registro pelo seu ID.

Para buscar, é necessário o envio da chave do composto na URL da requisição seguido da autenticação Acess Token no Header.

A chamada para obter os dados da consulta deve ser realizada utilizando um HTTP GET para o endereço de definição da API.

GET https://voice-api.zenvia.com/composto/{id}

Request

ID Obrigatório

ID do Composto para recuperar os dados

Response

dados object

Retorna o objeto composto

Relatório Composto

Definição

GET https://voice-api.zenvia.com/composto/relatorio

Request

curl -X GET --header 'Accept: application/json' \
            --header 'Access-Token: {{access-token}}' \
            'https://voice-api.zenvia.com/composto/relatorio?data_inicio=2018-03-14&data_fim=2018-03-15'

<?php
$client = new TotalVoiceClient('seu-token');

$response = $client->composto->relatorio($dataInicial, $dataFinal);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.composto.relatorio(data_inicial, data_final)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.Audio.Relatorio.Gerar(dataInicial, dataFinal)

from totalvoice.cliente import Cliente

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.composto.get_relatorio("2017-12-08T11:00:32-02:00", "2017-12-08T11:00:32-02:00")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Audio composto = new Audio(client);

JSONObject response = composto.relatorio(dataInicial, dataFinal);

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("{{access-token}}")
puts @client.composto.enviar("NUMERO-DESTINO", "URL-AUDIO")

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "relatorio": [
      {
        "id": 432,
        "numero_destino": "+5510999999999",
        "data_criacao": "2016-03-27T15:12:44+03:00",
        "data_inicio": "2016-03-27T15:12:49+03:00",
        "tipo": "fixo",
        "status": "atendida",
        "duracao_segundos": 45,
        "duracao": "00:00:45",
        "duracao_cobrada_segundos": 60,
        "duracao_cobrada": "00:00:60",
        "duracao_falada_segundos": 35,
        "duracao_falada": "00:00:35",
        "preco": 0.12,
        "resposta_usuario": true,
        "resposta": "8",
        "tags": "clienteX",
        "url_gravacao": "http://fooooo.bar/gravacao.mp3",
        "bina": "+5510888888888"
      },
      {
        "id": 433,
        "numero_destino": "+5510999999999",
        "data_criacao": "2016-03-27T15:12:44+03:00",
        "data_inicio": "2016-03-27T15:12:49+03:00",
        "tipo": "fixo",
        "status": "atendida",
        "duracao_segundos": 45,
        "duracao": "00:00:45",
        "duracao_cobrada_segundos": 60,
        "duracao_cobrada": "00:00:60",
        "duracao_falada_segundos": 35,
        "duracao_falada": "00:00:35",
        "preco": 0.12,
        "resposta_usuario": true,
        "resposta": "8",
        "tags": "clienteX",
        "url_gravacao": "http://fooooo.bar/gravacao.mp3",
        "bina": "+5510888888888"
      }
    ]
  }
}

Para consultar os compostos enviados, basta informar o período desejado para que a API retorne os dados.

Veja ao lado um exemplo de requisição. Os campos são:

Request

data_inicio Obrigatório Query String	Data inicial para consulta dos dados no relatório
data_fim Obrigatório Query String	Data final para consulta dos dados no relatório
posicao Opcional Query String	Posição para seleção dos dados do relatório - começa na posição 0. Também chamado de offset.
limite Opcional Query String	Quantidade de chamadas a retornar na consulta. O limite padrão é 100 e o máximo é 200.

Response

relatorio array

Retorna um array com objetos composto

TTS: Leitura de Texto

TTS Endpoint

https://voice-api.zenvia.com/tts

Usando esse recurso, você pode converter uma mensagem de texto em fala.

Dessa forma, quando o número de destino inserido atender, escutará uma voz falando a mensagem escrita por você.

Algumas opções adicionais podem ser também enviadas:

• Aguardar uma resposta do usuário;
• Gravar o áudio da ligação;
• Inserir um número bina que aparecerá no momento da ligação.

Objeto TTS:

TTS Endpoint

https://voice-api.zenvia.com/tts

JSON

{
    "id": 12345678,
    "numero_destino": "+5510999999999",
    "data_criacao": "2019-05-22T09:18:44.000-03:00",
    "data_inicio": "2019-05-22T09:18:44.000-03:00",
    "tipo": "movel",
    "status": "atendida",
    "duracao_segundos": 22,
    "duracao": "00:00:22",
    "duracao_cobrada_segundos": 60,
    "duracao_cobrada": "00:01:00",
    "duracao_falada_segundos": 2,
    "duracao_falada": "00:00:02",
    "preco": 0.35,
    "mensagem": "Olá, se você gostaria de utilizar a zenvia, digite 1.",
    "resposta_usuario": true,
    "resposta": "1",
    "motivo_desconexao": null,
    "url_gravacao": "https://voice-api.zenvia.com/rec/123456789",
    "bina": "+5510888888888"
}

O objeto é um modelo JSON que contém a mensagem de texto enviada para ser convertida em uma mensagem de voz.

Para realizar a chamada, é necessário que esta contenha os parâmetros solicitados abaixo na tabela Atributos. Ao final, a API fará o retorno.

No atributo “status”, os seguintes valores podem ser retornados:

• Preparando
• Chamando
• Atendida
• Ocupado
• Sem resposta
• Congestionado
• Falha
• Cancelada
• Desconhecido

Atributos

id integer	ID do registro do TTS.
numero_destino string	Número do destinatário que foi enviado o TTS.
data_criacao datetime	Data e hora que foi criado o registro.
data_inicio datetime	Data e hora que foi iniciado o processamento do TTS.
tipo string	Tipo de telefone: fixo, móvel ou ramal.
status string	Status do registro.
duracao_segundos integer	Duração total em segundos da chamada, desde o início do processamento.
duracao integer	Duração total da chamada desde o início do processamento
duracao_cobrada_segundos integer	Duração em segundos para fins de cobrança.
duracao_cobrada integer	Duração considerada para fins de cobrança.
duracao_falada_segundos integer	Duração em segundos da chamada desde que o destino atendeu.
duracao_falada integer	Duração da chamada desde que o destino atendeu.
preco float	Valor cobrado pela chamada.
mensagem float	Mensagem em forma de texto que você nos enviou.
resposta_usuario boolean	Valor enviado identificando se aceita a resposta do usuário.¹
resposta string	Se você enviou resposta_usuario = true, quando o usuário executa alguma ação no teclado númerico do dispositivo, o valor será exibido neste campo (DTMF).¹
motivo_desconexao string	Aqui é informado o motivo do derrubamento da ligação, você pode ver mais em motivos de desconecção
url_gravacao string	Quando enviado a opção Gravar Áudio = true, este campo disponibilizará uma URL contendo o áudio da gravação da ligação.
bina string	Número de telefone que aparece no identificador de quem recebe a chamada

Criar TTS

Definição

POST https://voice-api.zenvia.com/tts

Request

curl -X POST --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: seu-token' \
             -d '{"numero_destino":"+5510999999999", "bina": "+5510888888888", "mensagem":"Olá"}' \
             'https://voice-api.zenvia.com/tts'

<?php
require_once "vendor/autoload.php";
use TotalVoice\Client as TotalVoiceClient;

$client = new TotalVoiceClient('seu-token');
$response = $client->tts->enviar('+5510999999999', 'Olá, essa é a minha mensagem');

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.tts.enviar("+5510999999999", "Olá, essa é a minha mensagem")
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.Tts.Enviar("+5510999999999", "Olá, essa é a minha mensagem", false, "")

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.tts.enviar("+5510999999999", "Olá, essa é a minha mensagem")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Tts tts = new Tts(client);

JSONObject response = tts.enviar("+5510999999999", "Olá, essa é a minha mensagem");

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.tts.enviar("+5510999999999", "Olá, essa é a minha mensagem")

Response

{
    "status": 200,
    "sucesso": true,
    "motivo": 0,
    "mensagem": "tts criado com sucesso",
    "dados": {
        "id": 1234
    }
}

Para criar um TTS, basta informar o número de destino válido e a mensagem que será falada quando o mesmo atender a ligação.

POST: https://voice-api.zenvia.com/tts

REQUEST:

• Headers

1. Content-Type: application/json
2. Authorization: Access-Token: seu-token

Veja ao lado um exemplo de requisição. Os campos são:

Request

numero_destino Obrigatório	Número do telefone que irá receber a chamada, formato E.164: [+][DDI][DDD][Número]. Exemplo: +5510999999999.
mensagem Obrigatório	Mensagem que será falada quando o número destino atender a ligação. Exemplo: Olá, essa é a minha mensagem.
resposta_usuario Opcional	Aguardar uma resposta do destinatário.
tipo_voz Opcional	Idioma em que a mensagem deve ser lida e também o tipo da voz¹
bina Opcional	Número de telefone que aparecerá no identificador de quem receber a chamada, formato E.164: [+][DDI][DDD][Número]. Exemplo: +5510999999999
gravar_audio Opcional	Gravar a ligação
detecta_caixa Opcional	Caso seja identificado caixa postal a ligação será derrubada antes que inicie a mensagem para a caixa postal. Esse serviço tem um custo adicional.
bina_inteligente Opcional	Quando o valor for true, ao enviar o torpedo o número de telefone que aparecerá para o destino será um número com DDD de sua região. Veja DDDs disponíveis.

Response

id integer

Retorna o ID do TTS criado

¹ Lista de vozes disponíveis.

• br-Camila
• br-Vitoria
• br-Ricardo
• en-Joey
• en-Joanna
• fre-Celine
• fre-Mathieu
• ger-Vicki
• ger-Hans
• ita-Carla
• ita-Giorgio
• jap-Mizuki
• pol-Jan
• rus-Tatyana
• rus-Maxim
• esp-Conchita
• esp-Enrique

Buscar TTS

Definição

GET https://voice-api.zenvia.com/tts/{id}

Request

curl -X GET --header 'Content-Type: application/json' \
            --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' 'https://voice-api.zenvia.com/tts/id-tts'

<?php
require_once "vendor/autoload.php";
use TotalVoice\Client as TotalVoiceClient;

$client = new TotalVoiceClient('seu-token');
$response = $client->tts->buscaTTS(id-tts);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.tts.buscar(123)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.tts.Buscar(123)

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.tts.get_by_id(123)

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Tts tts = new Tts(client);

JSONObject response = tts.buscar(123);

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.tts.enviar("NUMERO-DESTINO", "MENSAGEM")

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "id": 123453,
    "numero_destino": "+5510999999999",
    "data_criacao": "2019-07-09T10:59:42.000-03:00",
    "data_inicio": "2019-07-09T10:59:43.000-03:00",
    "tipo": "movel",
    "status": "atendida",
    "duracao_segundos": 45,
    "duracao": "00:00:45",
    "duracao_cobrada_segundos": 0,
    "duracao_cobrada": "00:00:00",
    "duracao_falada_segundos": 0,
    "duracao_falada": "00:00:00",
    "preco": 0,
    "mensagem": "Mensagem de teste",
    "resposta_usuario": true,
    "resposta": 2,
    "motivo_desconexao": "16. normal",
    "url_gravacao": "",
    "bina": "+5510888888888"
  }
}

Caso deseje, após o envio do TTS, você poderá realizar a busca do registro pelo seu ID.

Para buscar, é necessário o envio da chave do TTS na URL da requisição seguido da autenticação Acess Token no Header.

A chamada para obter os dados da consulta deve ser realizada utilizando um HTTP GET para o endereço de definição da API.

GET https://voice-api.zenvia.com/tts/{id}

Request

ID Obrigatório

ID do TTS para recuperar os dados

Response

dados object

Retorna o objeto TTS

Relatório TTS

Definição

GET https://voice-api.zenvia.com/tts/relatorio

Request

curl -X GET --header 'Accept: application/json' \
            --header 'Access-Token: seu-token' \
            'https://voice-api.zenvia.com/tts/relatorio?data_inicio=2018-03-14&data_fim=2018-03-15'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->tts->relatorio($dataInicial, $dataFinal);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.tts.relatorio(data_inicial, data_final)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
 response, err := client.tts.Relatorio.Gerar(dataInicial, dataFinal)

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.tts.get_relatorio(data_inicio, data_fim)

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Tts tts = new Tts(client);

JSONObject response = audio.relatorio(dataInicial, dataFinal);

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.tts.enviar("NUMERO-DESTINO", "MENSAGEM")

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "relatorio": [
      {
        "id": 12345679,
        "numero_destino": "+5510999999999",
        "data_criacao": "2019-07-09T10:59:42.000-03:00",
        "data_inicio": "2019-07-09T10:59:43.000-03:00",
        "tipo": "movel",
        "status": "atendida",
        "duracao_segundos": 45,
        "duracao": "00:00:45",
        "duracao_cobrada_segundos": 0,
        "duracao_cobrada": "00:00:00",
        "duracao_falada_segundos": 0,
        "duracao_falada": "00:00:00",
        "preco": 0,
        "mensagem": "Olá, tudo bem?",
        "resposta_usuario": false,
        "resposta": null,
        "motivo_desconexao": "16. normal",
        "url_gravacao": "",
        "bina": "+5510888888888"
      },
      {
        "id": 13246578,
        "numero_destino": "+5510999999999",
        "data_criacao": "2019-07-09T15:33:01.000-03:00",
        "data_inicio": "2019-07-09T15:33:01.000-03:00",
        "tipo": "movel",
        "status": "ocupado",
        "duracao_segundos": 33,
        "duracao": "00:00:33",
        "duracao_cobrada_segundos": 0,
        "duracao_cobrada": "00:00:00",
        "duracao_falada_segundos": 0,
        "duracao_falada": "00:00:00",
        "preco": 0,
        "mensagem": "Olá esse é uma mensagem enviada por tts",
        "resposta_usuario": false,
        "resposta": null,
        "motivo_desconexao": "17. ocupado",
        "url_gravacao": "",
        "bina": "+5510888888888"
      }
    ]
  }
}

Para consultar os TTSs enviados, basta informar o período desejado para que a API retorne os dados.

Veja ao lado um exemplo de requisição. Os campos são:

Request

data_inicio Obrigatório Query String	Data inicial para consulta dos dados no relatório
data_fim Obrigatório Query String	Data final para consulta dos dados no relatório
posicao Opcional Query String	Posição para seleção dos dados do relatório - começa na posição 0. Também chamado de offset.
limite Opcional Query String	Quantidade de chamadas a retornar na consulta. O limite padrão é 100 e o máximo é 200.
destino Opcional Query String	Número de destino da chamada.

Response

relatorio array

Retorna um array com objetos TTS

SMS (descontinuado)

SMS Endpoint

https://voice-api.zenvia.com/sms

O SMS permite que você envie mensagens de texto pela nossa API. Você precisa informar um número de destino e uma mensagem a ser enviada. Existem algumas opções adicionais que permitem aguardar uma resposta do usuário, enviar multi sms ou agendar uma data de envio por exemplo.

Objeto Sms

JSON

{
    "id": 432,
    "numero_destino": "+5510999999999",
    "data_criacao": "2018-03-18T00:51:22.000Z",
    "mensagem": "Oi, tudo bem?",
    "preco": 0.09,
    "status_envio": "enviada",
    "data_status": "2018-03-19T00:51:36.000Z",
    "resposta_usuario": true,
    "respostas": [
      {
        "id": 2,
        "sms_id": 432,
        "resposta": "tudo bem, e voce?",
        "data_resposta": "2016-03-31T22:46:42-03:00"
      }
    ],
    "tags": null
}

Definição do objeto Sms

Atributos

id integer	ID do registro de SMS.
numero_destino string	Número do destinatário (móvel) que será enviado o SMS.
data_criacao datetime	Data e hora que foi criado o registro
mensagem string	Mensagem que será enviada para o número.
preco float	Valor cobrado pelo envio
status string	Status do registro: enviada: enviado para processamento erro: erro no processamento entregue: entregue para o número de destino aguardando: aguardando o envio para processamento em análise: conteúdo da mensagem em análise bloqueado: mensagem bloqueada por conteúdo proibido
data_status datetime	Data e hora que o status foi alterado
resposta_usuario boolean	Aguarda a resposta do usuário: sim ou não
respostas array	Array contendo os objetos de resposta
tags string	String com a tag enviado no momento do post.

Objeto Resposta SMS

JSON

{
  "id": 2,
  "sms_id": 3,
  "resposta": "tudo bem, e voce?",
  "data_resposta": "2016-03-31T22:46:42-03:00"
}

Definição do objeto Resposta SMS

Atributos

id integer	ID do registro de Resposta.
sms_id integer	ID do SMS vinculado a resposta.
resposta string	Texto com a resposta do usuário
data_resposta datetime	Data e hora que foi respondido pelo usuário

Enviar um SMS

Definição

POST https://voice-api.zenvia.com/sms

Request

curl -X POST --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: {{access-token}}' \
             -d '{"numero_destino":"+5510999999999","mensagem":"Ola tudo bem?"}' \
             'https://voice-api.zenvia.com/sms'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->sms->enviar('+5510999999999', 'Ola tudo bem?');

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.sms.enviar("+5510999999999", "Ola tudo bem?")
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
response, err := client.SMS.Enviar("+5510999999999", "Ola tudo bem?", false, false, nil)

from totalvoice.cliente import Cliente

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.sms.enviar("+5510999999999", "Ola tudo bem?")

TotalVoiceClient client = new TotalVoiceClient("seu-token");

Sms sms = new Sms(client);
JSONObject response = sms.enviar("+5510999999999", "Ola tudo bem?");

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.sms.enviar("+5510999999999", "Ola tudo bem?")

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "sms criado com sucesso",
  "dados": {
    "id": 4921
  }
}

Para o envio de SMS é necessário informar um número móvel válido e uma mensagem de texto.

Request

numero_destino Obrigatório	Número do telefone móvel que irá receber a mensagem de texto.
mensagem Obrigatório	Mensagem de texto para ser enviada com limite de 160 caracteres e não aceita acentos.
resposta_usuario Opcional, default false	Aguardar uma resposta do destinário.
multi_sms Opcional default false	Aceita SMS com mais de 160 caracteres, máximo é de 16.000 caracteres. Envia multiplos SMSs para o mesmo número (um a cada 160 caracteres) e retorna array de IDs.
tags Opcional	Você pode enviar informações em texto no campo tags com até 50 caracteres.
data_criacao Opcional default null	Informe uma data e hora para agendar a entrega do SMS. vazio = liga imediatamente. Data e Hora no formato UTC.

Response

id integer/array

A resposta pode ser um Objeto com o ID do SMS, ou um array com vários IDs caso seja setado para o envio de multi_sms = true.

Buscar SMS

Definição

GET https://voice-api.zenvia.com/sms/{id}

Request

curl -X GET --header 'Content-Type: application/json' \
            --header 'Accept: application/json' \
            --header 'Access-Token: {{access-token}}' 'https://voice-api.zenvia.com/sms/1'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->sms->buscaSms(123);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.sms.buscar(123)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
response, err := client.SMS.Buscar(123)

from totalvoice.cliente import Cliente

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.sms.get_by_id("123")

TotalVoiceClient client = new TotalVoiceClient("seu-token");

Sms sms = new Sms(client);
JSONObject response = sms.buscar(123);

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.sms.buscar(123)

Response

{
   "status":200,
   "sucesso":true,
   "motivo":0,
   "mensagem":"dados retornados com sucesso",
   "dados":{  
      "id":25536757,
      "numero_destino":"+5510999999999",
      "data_criacao":"2019-05-29T17:49:00.000-03:00",
      "mensagem":"Ola tudo bem?",
      "preco":0.045,
      "status_envio":"enviada",
      "data_status":null,
      "resposta_usuario":false,
      "respostas":[  

      ],
      "tags":"informações adicionais"
}

Após o envio de mensagens de SMS você poderá realizar a busca do registro pelo seu ID.

Request

ID Obrigatório

ID do SMS para recuperar os dados

Response

dados object

Retorna o objeto SMS

Relatório SMS

Definição

GET https://voice-api.zenvia.com/sms/relatorio

Request

curl -X GET --header 'Accept: application/json' \
            --header 'Access-Token: {{access-token}}' \
            'https://voice-api.zenvia.com/sms/relatorio?data_inicio=2018-03-14&data_fim=2018-03-15'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->sms->relatorio($dataInicial, $dataFinal);

const totalvoice = require('totalvoice-node');
const client = new totalvoice("seu-token");

client.sms.relatorio(data_inicial, data_final)
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("seu-token")
response, err := client.SMS.Relatorio.Gerar(dataInicial, dataFinal)

from totalvoice.cliente import Cliente

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.sms.get_relatorio("2017-12-08T11:00:32-02:00", "2017-12-08T11:00:32-02:00")

TotalVoiceClient client = new TotalVoiceClient("seu-token");

Sms sms = new Sms(client);
JSONObject response = sms.relatorio(dataInicial, dataFinal);

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.sms.relatorio(data_inicial, data_final)

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "relatorio": [
      {
        "id": 151,
        "numero_destino": "+5510999999999",
        "data_criacao": "2016-03-30T23:34:08-03:00",
        "data_envio": null,
        "mensagem": "Mensagem de teste",
        "preco": 0,
        "status": "enviada",
        "resposta_usuario": false,
        "respostas": []
      },
      {
        "id": 204,
        "numero_destino": "+5510999999999",
        "data_criacao": "2016-03-31T22:39:36-03:00",
        "data_envio": null,
        "mensagem": "Oi, tudo bem?",
        "preco": 0.05,
        "status": "enviada",
        "resposta_usuario": true,
        "respostas": [
          {
            "id": 2,
            "resposta": "tudo bem, e voce?",
            "data_resposta": "2016-03-31T22:46:42-03:00"
          }
        ]
      }
    ]
  }
}

Você pode consultar os SMSs enviados posteriormente. Basta informar o período desejado para que a API retorne os dados.

Request

data_inicio Obrigatório Query String	Data inicial para consulta dos dados no relatório
data_fim Obrigatório Query String	Data final para consulta dos dados no relatório
posicao Opcional Query String	Posição para seleção dos dados do relatório - começa na posição 0. Também chamado de offset.
limite Opcional Query String	Quantidade de chamadas a retornar na consulta. O limite padrão é 100 e o máximo é 200.

Response

relatorio array

Retorna um array com objetos SMS