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

Áudio

Áudio Endpoint

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

A funcionalidade de Envio de Áudio permite que você envie um torpedo de voz ou mensagens de voz do tipo áudio para determinados números. Basta você informar um número destino e a URL contendo o seu arquivo de áudio. Estes arquivos devem estar disponíveis em uma URL pública. Você poderá enviar algumas opções adicionais, tais como, aguardar uma resposta do usuário, gravar o áudio da ligação ou colocar um número bina que aparecerá no momento da ligação.

Formatos aceitos:

• .mp3
• .wav

Tamanho máximo:

• 5MB

Objeto Áudio

JSON

{
    "id": 12345678,
    "numero_destino": "48912341234",
    "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": "+5548988888888",
    "chamada_verificada": true,
    "motivo_vcall": {
        "id": 123,
        "mensagem": "Texto do motivo"
    }
}

Definição do objeto Áudio

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
chamada_verificada boolean	Se o áudio foi enviado com chamada verificada
motivo_vcall objeto	Objeto do tipo Motivos VCall

¹ Após o usuário digitar algo no teclado númerico a ligação será derrubada.

Criar um á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":"+5548988881111", "bina": "+554811111111" ,"url_audio":"http://sua.url.audio/audio.mp3", "chamada_verificada": true, "motivo_vcall": 57}' \
             '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('4811111111', 'http://sua.url.audio/audio.mp3');

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

client.audio.enviar("4811111111", "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("4811111111", "http://sua.url.audio/audio.mp3", false, "")

from totalvoice.cliente import Cliente

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.audio.enviar("4811111111", "http://sua.url.audio/audio.mp3")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Audio audio = new Audio(client);

JSONObject response = audio.enviar("4811111111", "http://sua.url.audio/audio.mp3");

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.audio.enviar("4811111111", "http://sua.url.audio/audio.mp3")

Response

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

Basta informar o número de destino válido e a URL pública do arquivo.

Request

numero_destino Obrigatório	Número do telefone que irá receber a chamada, formato DDD + Número, exemplo: 4832830151.
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 DDD + Número, exemplo: 4832830151.
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.
chamada_verificada Opcional	Um valor booleano para identificar se o áudio terá chamada verificada
motivo_vcall Opcional	Id do motivo vcall da chamada verificada

Response

id integer

Retorna o ID do Áudio.

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": "4832830151",
        "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": "+5548988888888",
        "chamada_verificada": true,
        "motivo_vcall": {
            "id": 123,
            "mensagem": "Texto do motivo"
        }
    }
}

Após o envio de mensagens de áudio, você poderá realizar a busca do registro pelo seu ID.

Request

id Obrigatório

ID do Áudio para recuperar os dados

Response

dados object

Retorna o objeto áudio

Relatório á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": "4832830151",
        "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": "+5548988888888",
        "chamada_verificada": true,
        "motivo_vcall": {
            "id": 123,
            "mensagem": "Texto do motivo"
        }
      },
      {
        "id": 432,
        "numero_destino": "4832830151",
        "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": "+5548988888888",
        "chamada_verificada": false,
        "motivo_vcall": {
            "id": null,
            "mensagem": null
        }
      }
    ]
  }
}

Você pode consultar os áudios 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 áudio

Exemplo: Se você tiver um relatório com 350 áudios, na primeira página será retornado 200. Para pegar os dados da segunda página o valor da posição deve ser 201.

Central Telefônica

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

Caso você deseje utilizar a API de Voz da ZenAPI para ligações receptivas, entre em contato conosco para a contratação de um número receptivo(DID).

Objeto Ramal

JSON

{
    "id": 76498,
    "ramal": "3333",
    "login": "testee@zenvia.com",
    "bina": "48999999999",
    "webphone_key": "213kbbncs324454ASDcxzln123",
    "ligacao_externa": true,
    "ligacao_celular": true,
    "gravar_audio": true,
    "acesso_gravacoes": true,
    "webphone": false,
    "ura_id": null,
    "voicemail": false,
    "tags": "",
    "motivo_vcall": {
        "id": 53,
        "motivo": "Estamos retornando a sua solicitação"
    }        
}

Definição do objeto 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
motivo_vcall objeto	Objeto do tipo Motivos VCall

Criar um 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,
    "motivo_vcall": null
  }
}

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

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)
motivo_vcall integer	Id do motivo vcall

Response

dados object

Retorna o objeto com os dados do ramal criado

Buscar um 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": "48999999999",
    "webphone_key": "testefd3b268b3de8cateste44968",
    "ligacao_externa": true,
    "ligacao_celular": true,
    "gravar_audio": true,
    "acesso_gravacoes": true,
    "webphone": false,
    "ura_id": null,
    "voicemail": false,
    "tags": "",
    "motivo_vcall": null
  }
}

Após o ramal ser criado, você pode consultar suas informações

Request

id integer

ID do ramal

Response

dados object

Retorna o objeto do ramal

Editar um 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
}

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)
motivo_vcall integer	Id do motivo vcall

Response

status object

Retorna o status da requisição

Editar um 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
    }
  ]
}

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 um 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
}

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": "48999999999",
        "webphone_key": "totalTesteb8af64668997totalTeste",
        "ligacao_externa": true,
        "ligacao_celular": true,
        "gravar_audio": true,
        "acesso_gravacoes": false,
        "webphone": true,
        "ura_id": null,
        "voicemail": false,
        "tags": "",
        "motivo_vcall": {
            "id": 53,
            "motivo": "Estamos retornando a sua solicitação"
        }
      },
      {
        "id": 4567,
        "ramal": "4001",
        "login": "teste1@totalTeste.com.br",
        "bina": "48999999999",
        "webphone_key": "teste18e990a500a059a78teste1",
        "ligacao_externa": true,
        "ligacao_celular": true,
        "gravar_audio": true,
        "acesso_gravacoes": true,
        "webphone": true,
        "ura_id": null,
        "voicemail": false,
        "tags": "",
        "motivo_vcall": null
      }
    ]
  }
}

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

Importante: Se você tiver um relatório com 350 ramais, na primeira página será retornado 200. Para pegar os dados da segunda página o valor da posição deve ser 201.

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"
      }
    ]
  }
}

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

Importante: Se você tiver um relatório com 350 pausas do ramal, na primeira página será retornado 200. Para pegar os dados da segunda página o valor da posição deve ser 201.

Listar ligações de um 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": "48999999999",
        "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": "48999999999",
        "status": "atendida",
        "duracao_segundos": 596,
        "duracao": "00:09:56",
        "preco": "0.00",
        "ramal": {
          "id": 1234,
          "ramal": "4000",
          "login": "teste@totaltestevoice.com.br"
        }
      }
    ]
  }
}

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

Importante: Se você tiver um relatório com 350 pausas do ramal, na primeira página será retornado 200. Para pegar os dados da segunda página o valor da posição deve ser 201.

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"
            }
        }
    ]
}

Uma URA possui uma estrutura de atendimento, em nossa api você tem diversas possibilidades. Após os atributos, iremos apresentar todos os Parâmetros que podem ser utilizados.

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.

Opções adicionais para ação

opcao string	Caso você tenha adicionado uma 'opcao' na etapa da URA ela só será chamada caso o usuário digite o número dela. As opções vão de 1 à 9.
menu string	Indica a qual menu pertence essa etapa da URA.
timeout string	Este é o tempo de espera para que a ligação seja derrubada ou a URA vá para a próxima ação, ele começa a conta após a sua ação acabar. Exemplo: assim que acabar o texto do seu TTS.
coletar_dtmf string	Isso indica que essa etapa da ação irá esperar no máximo a quantidade de caracteres que você passar. Por exemplo: {"coletar_dtmf":"11"}. Quando atingido o máximo de DTMF(ou acabar o timeout) será executada a próxima ação.
queue_fail_timeout string	Quando você utiliza a ação 'fila' você pode usar esse parâmetro passando o tempo máximo de espera da fila, após o término do tempo a próxima ação será executada.

Criar uma 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
  }
}

Veja a lista de opções dos dados/estrutura da URA que podem ser utilizadas.

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 uma 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"
        }
      }
    ]
  }
}

Request

id integer

ID da URA

Response

dados object

Retorna o objeto da URA

Editar uma 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
  }
}

Request

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

Response

status object

Retorna o status da requisição

Deletar uma 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
}

Request

id integer

ID da URA

Response

status object

Retorna o status da requisição

Relatório de 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"
            }
          }
        ]
      }
    ]
  }
}

Response

relatorio array

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

Fila

Fila Endpoint

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

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

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"     
      }
    ]
}

Definição do objeto 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 uma 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
    }
}

Basta informar o nome da fila e a estratégia de ring.

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"
      }
    ]
  }
}

Após a criação de uma fila, você poderá realizar a busca do registro pelo seu 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
}

Altera as informações da sua fila.

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 um ramal na fila

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
  }
}

Basta informar o id da fila e por parâmetro o id do ramal.

Request

ramal_id Obrigatório

ID do ramal para ser adicionado

Deletar um ramal da fila

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"
}

Basta informar o id da fila e por parâmetro o id do ramal para ser removido.

Request

ramal_id Obrigatório

ID do ramal para ser removido

Busca um ramal da fila

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"
      }
    ]
  }
}

Basta informar o id da fila e o id do ramal.

Request

id Obrigatório	ID da fila.
ramal_id Obrigatório	ID do ramal.

Relatório chamadas de uma 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": "554831810323",
        "numero_origem": "4712344321",
        "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": "554831810323",
        "numero_origem": "4840421210",
        "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"
        }
      }
    ]
  }
}

Você pode consultar os áudios enviados posteriormente. Basta informar o período desejado para que a API retorne os dados.

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

Exemplo: Se você tiver um relatório com 350 chamadas, na primeira página será retornado 200. Para pegar os dados da segunda página o valor da posição deve ser 201.

Chamadas

Chamada Endpoint

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

A funcionalidade Chamada permite que você crie chamadas perna A e perna B, podendo gravar as ligações, agendar e binar o seu próprio número. Permite gerar relatório de chamadas, derrubar chamadas em andamento, transferir chamadas e avaliação de chamadas.

Objeto Chamada

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"
    }
 }

Definição do objeto 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"
}

Definição do objeto Origem/Destino: Estes objetos contêm basicamente a mesma estrutura de informações com relação às chamadas. A Origem, contém as informações de quem originou a ligação e o Destino de quem recebeu a ligação. É nesses objetos que você irá encontrar as informações de duração das chamadas, status e o preço que foi cobrado por cada perna.

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 uma 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":"4811111111",
                    "numero_destino":"4811111112",
                    "data_criacao":"2021-04-08T17:21:20Z",
                    "gravar_audio":"true",
                    "bina_origem":"4832830151",
                    "bina_destino":"4832830152",
                    "tags":"clienteUm",
                    "detecta_caixa_origem":"true"
                 }' 
             'https://voice-api.zenvia.com/chamada'

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

$response = $client->chamada->ligar('4811111111', '4811111112');

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

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

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

from totalvoice.cliente import Cliente

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

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

JSONObject response = chamada.ligar("4811111111", "4811111112");

require 'totalvoice-ruby'
include TotalVoice

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

Response

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

Basta informar o número de origem e destino.

Request

numero_origem Obrigatório string	Número origem (perna A), recebe a chamada primeiro do número destino. Exemplo: 4832830151
numero_destino Obrigatório string	Número destino (perna B), recebe a chamada após o número origem atender. Exemplo: 4832830151
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 DDD + Número, exemplo: 4832830151
bina_destino Opcional string	Número de BINA que será apresentado na chamada para o número destino (perna B). Formato DDD + Número, exemplo: 4832830151
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

Desligando uma 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("4811111111", "http://foo.bar/audio.mp3")

Response

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

Basta informar o id da chamada ativa

Request

id integer

ID da chamada ativa

Buscar uma 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" : "+27921815114"
     },
     "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" : "+73970934836"
     }
  }
}

Após o envio de chamadas, você poderá realizar a busca do registro pelo seu 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"
}

Você poderá realizar o download do áudio da chamada. Esta funcionalidade estará disponível se você setou a opção "Gravar Audio" igual a True no momento da criação da chamada.

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" : "+27921815114"
        },
        "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" : "+73970934836"

        }
      }
    ]
  }
}

Você pode consultar as Chamadas enviadas. 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
origem Opcional Query String	Número de telefone de origem para filtrar. Ex.: 4832830151
destino Opcional Query String	Número de telefone de destino para filtrar. Ex.: 4832830151
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

Escuta de 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":"4811111111", "modo": 1}' \
             'https://voice-api.zenvia.com/chamada/123/escuta'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->chamada->escutar(123, '4811111111', 1);

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

client.chamada.escutar(123, "4811111111", 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, "4811111111", 1)

from totalvoice.cliente import Cliente

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

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Chamada chamada = new Chamada(client);
JSONObject response = chamada.escutar(123, "4811111111", 1);

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.chamada.escutar(123, "4811111111", 1)

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "escuta criada com sucesso"
}

Você pode realizar uma escuta para uma chamada que está ativa (Beta).

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

Transferência de 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":"4811111111", "perna": "destino"}' \
            'https://voice-api.zenvia.com/chamada/123/transfer'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->chamada->transferir(123, '4811111111', 'destino');

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

client.chamada.transferir(123, "4811111111", "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, "4811111111", "destino")

from totalvoice.cliente import Cliente

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

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Chamada chamada = new Chamada(client);
JSONObject response = chamada.transferir(123, "4811111111", "destino");

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.chamada.transferir(123, "4811111111", "destino")

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "a chamada está sendo transferida"
}

Transfere a origem ou destino para outro telefone e desconecta a outra perna (Beta).

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

Avaliação de 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"
}

Avalie a Chamada para ter estatísticas de qualidade de seus clientes.

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.

Composto

Composto Endpoint

https://voice-api.zenvia.com/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.

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, ele já é transferido para o telefone de remarcação. JSON DADOS do exemplo:

[
    {
        "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": "1132830151",
                         "bina": "1132830152" 
                    }
    } 
]

O composto aceita um JSON com as seguintes opções:

• audio
• tts
• transferir
• ura

Você pode ver como funciona o envio de dados vendo a utlização em curl

As regras para o arquivo de áudio são as mesmas:

Formatos aceitos:

• .mp3
• .wav

Tamanho máximo:

• 5MB

Objeto Composto

JSON

{
    "id": 432,
    "numero_destino": "4832830151",
    "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": "+5548988888888",
    "chamada_verificada": true,
    "motivo_vcall": {
        "id": 123,
        "mensagem": "Texto do motivo"
    }

}

Definição do objeto Composto

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
chamada_verificada boolean	Se o composto foi enviado com chamada verificada
motivo_vcall objeto	Objeto do tipo Motivos VCall

Criar um 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":"+551132830151",
                "chamada_verificada": true, 
                "motivo_vcall": 57,
                "bina": "+5548988881111",
                "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":"+554832830151",
                            "bina":"+554832830152"
                        }
                    },
                        {  
                        "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":"4832830151","bina":"4832830152"}}]';
$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":"4832830151","bina":"4832830152"}}]','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":"4832830151","bina":"4832830152"}}]','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":"4832830151",
         "bina":"4832830152"
      }
   },
    {  
      "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":"4832830151","bina":"4832830152"}}]','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":"4832830151","bina":"4832830152"}}]','11987654321' , 'tags')

Response

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

Basta informar o número de destino válido e um JSON com o composto

Request

numero_destino Obrigatório	Número do telefone que irá receber a chamada, formato DDD + Número exemplo: 4832830151
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 DDD + Número exemplo: 4832830151
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.
chamada_verificada Opcional	Um valor booleano para identificar se o composto terá chamada verificada
motivo_vcall Opcional	Id do motivo vcall da chamada verificada

Response

id integer

Retorna o ID do Composto

¹ Você pode ver como funciona o envio de dados vendo a utlização em curl

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": "4832830151",
        "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": "+5548988888888",
        "chamada_verificada": true,
        "motivo_vcall": {
            "id": 123,
            "mensagem": "Texto do motivo"
        }
    }
}

Após o envio de mensagens composto, você poderá realizar a busca do registro pelo seu 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": "4832830151",
        "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": "+5548988888888",
        "chamada_verificada": true,
        "motivo_vcall": {
            "id": 123,
            "mensagem": "Texto do motivo"
        }
      },
      {
        "id": 433,
        "numero_destino": "4832830151",
        "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": "+5548988888888",
        "chamada_verificada": false,
        "motivo_vcall": {
            "id": null,
            "mensagem": null
        }
      }
    ]
  }
}

Você pode consultar os compostos 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 composto

Conferências

Conferência Endpoint

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

Conferências são como salas privadas que você cria e recebe um ID, só você com esse código consegue realizar chamadas que ao serem atendidas, conectam-se a essa conferência.

Objeto Conferência

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": "4832830151",
                  "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"                  
          }
    ]
}

Definição do objeto Conferência

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": "4832830151",
    "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"                  
}

Definição do objeto da Chamada da Conferência

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":"4811111111","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("4811111111", "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("4811111111", "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("4811111111", "http://foo.bar/conferencia.mp3");

Response

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

Basta chamar o metodo cria_conferencia para criar o id da sua 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": "4832830151",
        "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"
    }
}

Após o envio de mensagens de conferência, você poderá realizar a busca do registro pelo seu ID.

Request

ID Obrigatório

ID da Conferência para recuperar os dados

Response

dados object

Retorna o objeto conferência

Encerrar 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": "4832830151",
        "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": "4832830151",
        "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
      }
    ]
  }
}

Você pode consultar as conferências enviadas 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 conferência

DIDs

Objeto DID

Did Endpoint

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

JSON

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

Definição do objeto Áudio

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

A funcionalidade DID (Número de telefone para recebimento de chamadas) permite que você gerencie, adquire ou remova um DID da sua Conta. Também será possível extrair relatórios dos DIDs adquiridos e das chamadas recebidas por um número específico da sua Conta.

Consulta DIDs

Lista todos os DIDs da sua conta

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": "552120128207"
      }
    ]
  }
}

Request

Não precisa passar nenhum parâmetro.

Response

relatorio array

Retorna um array com objetos 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
}

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

Importante¹: Você só pode passar uma das opções, ou uma ura_id ou um ramal_id.

Definição

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

Request

curl -X DELETE --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: seu-token' \
             '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": "Did Removido com sucesso",
  "dados": null
}

Request

id integer

ID do DID

Response

dados object

Retorna o status da requisição

Estoque de DIDs

Nota: Para adquirir um DID você deve ter o cartão de crédito cadastrado na plataforma.

Did Endpoint

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

Request

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

<?php
Em construção

Em construção<aside class="notice"> Antes era possível consultar os números de DIDs disponíveis e comprá-los automaticamente. Atualmente é necessário entrar em contato com o time de suporte da equipe de voz da Zenvia pelo email  <a href="">suporte.voz@zenvia.com</a>
</aside>

Em construção

Em construção

Em construção

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "dados retornados com sucesso",
  "dados": {
    "dids": [
      {
        "id": 12341,
        "cidade": "SAO PAULO",
        "estado": "SP",
        "numero": "5511203729395"
      },
      {
        "id": 12341,
        "cidade": "Campinas",
        "estado": "SP",
        "numero": "5519350128096"
      }
    ]
  }
}

Request

Não precisa passar nenhum parâmetro.

Response

relatorio array

Retorna um array com objetos DIDs disponíveis.

Comprar DID

Para adquirir um DID você deve ter um cartão de crédito cadastrado na plataforma.

Did Endpoint

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

Request

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

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": {
    "dids": [
      {
        "id": 12341,
        "cidade": "SAO PAULO",
        "estado": "SP",
        "numero": "5511203729395"
      },
      {
        "id": 12341,
        "cidade": "Campinas",
        "estado": "SP",
        "numero": "5519350128096"
      }
    ]
  }
}

Request

did_id Obrigatório

Id do DID que será comprado

Response

dados object

Retorna o id do DID adquirido.

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": "552120182097",
    "numero_origem": "4831810323",
    "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": []
  }
}

Definição do objeto Chamada DID

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 uma 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": "554811111111",
        "numero_origem": "554811111111",
        "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ê pode 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.

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": "554811111111",
        "numero_origem": "554811111111",
        "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ê pode 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.

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. Ex.: 4832830151
destino Opcional Query String	Número de telefone de destino para filtrar. Ex.: 4832830151
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": "554811111111",
        "numero_origem": "554811111111",
        "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ê pode consultar as Chamadas recebidas por todos DIDs. 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
origem Opcional Query String	Número de telefone de origem para filtrar. Ex.: 4832830151
destino Opcional Query String	Número de telefone de destino para filtrar. Ex.: 4832830151
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

Gerenciar Contas

Gerenciar Contas End Point

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

Com a funcionalidade de Gerente de Contas você pode criar, consultar, alterar e deletar contas filhas, sendo as contas filhas exatamente iguais a qualquer outra conta na Zenvia, apenas são vinculadas com uma conta pai que tem o controle sobre ela, tendo o intuito 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": "4832830151",
    "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,
}

Definição do objeto 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"
    }
}

Cria uma nova conta filha.

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": "4832830151",
        "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,
    }
}

Busca os detalhes de uma conta filha.

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
}

Altera 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.

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
}

Deleta permanentemente uma conta filha, ficando indisponível para uma posterior consulta, tome muito cuidado ao executar este comando, após deletada, a conta filha irá perder todos os acessos à Zenvia, com isso o login utilizdo ficará disponível (pois não é possível logins duplicados na API).

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": "4832830151",
        "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": "4832830151",
        "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
      }
    ]
  }
}

Retorna um relatório com todas as suas contas filhas. As contas retornadas no relatório vem 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"
}

Permite adicionar crédito de bônus nas contas criadas por mim.

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

Listar Webhooks

Este método permite a listagem de todos os webhooks default configurados para suas subcontas(Contas filhas). Clique aqui para obter mais informações sobre cada webhook da ZenAPI.

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"
      },
    ]
  }
}

Request

Não precisa passar nenhum parâmetro.

Response

webhooks array

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

Remover Webhook

Este método permite a remoção de um webhook default específico.Clique aqui para obter mais informações sobre cada webhook da ZenAPI.

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
}

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
}

Altera as informações de um webhook default, 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

Minha Conta Endpoint

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

O Minha Conta permite que você visualize seu saldo, monitore suas contas e suas recargas, edite suas contas e configure e visualize 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": "4832830151",
    "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
}

Definição do objeto 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": "4832830151",
    "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
}

Definição do objeto resposta Minha 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

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
  }
}

Response

saldo float

Saldo atual da sua conta

Buscar minha 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": "4832830151",
    "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
  }
}

Response

dados object

Retorna o objeto Minha Conta

Alterar sua 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
}

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

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"
      }
    ]}
}

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"
  }
}

Request

url_retorno Opcional

URL para retorno depois da recarga ou ao cancelar.

Response

url string

URL para acessar o painel de recarga

Listar Webhooks

Este método permite a listagem de todos os webhooks configurados da sua conta. Clique aqui para obter mais informações sobre cada webhook da ZenAPI.

Definição

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

Request

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

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

var response = client.perfil.webhooks();

client := totalvoice.NewTotalVoiceClient("Seu_Token")

 response, err := client.Webhook.Listar()

from totalvoice.cliente import Cliente

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

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

puts @client.perfil.webhooks()

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"
      },
    ]
  }
}

Request

Não precisa passar nenhum parâmetro.

Response

webhooks array

Retorna dentro de dados um arrays com os webhooks cadastros.

Remover Webhook

Este método permite a remoção de um webhook específico de sua conta. Clique aqui para obter mais informações sobre cada webhook da ZenAPI.

Definição

DELETE https://voice-api.zenvia.com/webhook/{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/webhook/chamada_fim'

<?php
$response = $client->perfil->excluirWebhook("chamada_fim");

var response = client.perfil.excluirWebhook("chamada_fim");

client := totalvoice.NewTotalVoiceClient("Seu_Token")

 response, err := client.Webhook.Excluir("chamada_fim")

from totalvoice.cliente import Cliente

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

Perfil perfil = new Perfil(client);
JSONObject response = perfil.excluirWebhook("chamada_fim");

puts @client.perfil.excluir_webhook("chamada_fim")

Response

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

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/webhook/{nome_webhook}

Request

curl 'https://voice-api.zenvia.com/webhook/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->perfil->salvaWebhook("chamada_fim", "www.urlretorno.com.br");

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

client.perfil.salvaWebhook("chamada_fim", "www.urlretorno.com.br")
    .then(function(data) {
        console.log(data);
    })
    .catch(function(error) {
        console.log('Erro: ', error)
    });

client := totalvoice.NewTotalVoiceClient("Seu_Token")

response, err := client.Webhook.Salva("chamada_fim", "www.urlretorno.com.br")

from totalvoice.cliente import Cliente

client = Cliente("Seu_Token", 'voice-api.zenvia.com')
response = client.perfil.editar_webhook("chamada_fim", "www.urlretorno.com.br")

TotalVoiceClient client = new TotalVoiceClient("Seu_Token");
Perfil perfil = new Perfil(client);
JSONObject response = perfil.salvaWebhook("chamada_fim", "www.urlretorno.com.br");

puts @client.perfil.salva_webhook("chamada_fim", "www.urlretorno.com.br")

Response

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

Altera as informações de um webhook default, 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

Bina

Bina Endpoint

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

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

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.

Tendo a sua bina cadastrada e aprovada, você pode vincular Motivos VCall (Motivos de Chamadas Verificadas) a ela.

Chamadas Verificadas são um recurso para prevenir spam e golpes por telefone, ao mesmo tempo em que ajuda empresas legítimas a transmitirem mais confiança e segurança para os seus clientes.

Para utilizar as Chamadas Verificadas, é necessário fazer a contratação prévia da funcionalidade.

Objeto Bina

JSON

{
    "id": 432,
    "numero_telefone": "+5548911111111",
    "data_criacao": "2018-03-18T00:51:22.000Z",
    "fixo": false,
    "confirmado": true,
    "chamadas_verificadas": [
        {
            "id": 53,
            "motivo": "Estamos retornando a sua solicitação",
            "status": "Aprovado"
        }
    ]
}

Definição do objeto 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ê
chamadas_verificadas array	Um array de Motivos VCall

Objeto Motivo VCall

JSON

{
    "id": 53,
    "motivo": "Estamos retornando a sua solicitação",
    "status": "Aprovado"
}   

Motivo VCall são os motivos das Chamadas Verificadas. Os Motivos Vcall são vinculados a bina e são cadastrados atráves do painel em voice-app.zenvia.com/painel/

Definição do objeto Motivo VCall

Atributos

id integer	ID do motivo da Chamada Verificada
motivo string	Motivo da Chamada Verificada que aparecerá no display do aparelho celular do destino
status string	Informa qual o status do motivo da Chamada Verificada. Pode ser Aprovado | Em análise | Recusado

Cadastrar uma Bina

Definição

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

Request

curl -X POST --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             --header 'Access-Token: {{access-token}}' \
             -d '{"telefone":"+5548988888888", "mensagem_sms": "Teste SMS", "mensagem_tts": "Teste TTS"}' \
             'https://voice-api.zenvia.com/bina'

Envia um número de telefone para que receba um código via SMS (celular) ou TTS (fixo). Nossa API identificará automaticamente o tipo de número (fixo ou móvel) e enviará a mensagem com o código.

Request

telefone Obrigatório string	Número do telefone que irá receber a Chamada (fixo) ou SMS (móvel) com o código para validação
mensagem_sms Opcional string	Mensagem customizada para validação da Bina para números móveis (SMS). Temos a opção de enviar uma mensagem customizada com formatação de String (%s)
mensagem_tts Opcional string	Mensagem customizada para validação da Bina para números fixos (TTS). Temos a opção de enviar uma mensagem customizada com formatação de String (%s)

Response

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "Código enviado com sucesso",
  "dados": null
}

Null Null

O retorno é nulo, apenas uma mensagem informando que o código foi enviado para o número fornecido

Validar uma Bina

Definição

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

Request

curl -X GET --header 'Content-Type: application/json' \
            --header 'Accept: application/json' \
            --header 'Access-Token: {{access-token}}' \
            'https://voice-api.zenvia.com/bina?codigo=1234&telefone=+5548988888888'

Você deve informar o número do telefone e o código recebido no celular (SMS) ou telefone (TTS) informados no método POST, para realizarmos a validação

Request

telefone Obrigatório Query String	Número do telefone que será validado
codigo Obrigatório Query String	Código que será validado

Response

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "Verificação realizada com sucesso",
  "dados": {"valido": true, "id": 1}
}

valido booleano	Retorna true se o código e o número conferem. Caso contrário retorna false
id Integer	Retorna o ID da bina cadastrada

Buscar uma 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'

Após a criação de uma bina, você poderá realizar a busca do registro pelo seu 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": "+5548988888888",
    "data_criacao": "2018-03-18T00:51:22.000Z",
    "fixo": false,
    "confirmado": true,
    "chamadas_verificadas": [
        {
            "id": 2678,
            "motivo": "Estamos retornando sua solicitação de contato",
            "status": "Aprovado"
       },
       {
            "id": 2998,
            "motivo": "Estamos retornando sua solicitação de contato",
            "status": "Aprovado"
       }
    ]
}
}

dados object

Retorna o objeto Bina

Deletar uma 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'

Apaga o número de telefone (Bina) cadastrado na Conta. Você deve informar o ID da bina que deseja remover.

Caso a Bina esteja vinculada ao Caller ID Default ou à um motivo de Chamada Verificada, será necessário desvincular via painel de voz, antes de deletar.

Request

ID Obrigatório

ID da Bina a ser removida

Response

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

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'

Busca os telefones (Bina) cadastrados na Conta

Response

Response

{
  "status": 200,
  "sucesso": true,
  "motivo": 0,
  "mensagem": "Dados retornados com sucesso",
  "dados": [
        {
            "id": 432,
            "numero_telefone": "+554832830151",
            "data_criacao": "2016-03-27T15:12:44+03:00",
            "fixo": true,
            "confirmado": true,
            "chamadas_verificadas": [
                {
                    "id": 53,
                    "motivo": "Estamos retornando sua solicitação de contato",
                    "status": "Aprovado"
                },
                {
                    "id": 99,
                    "motivo": "Estamos retornando sua solicitação de contato",
                    "status": "Aprovado"
                }
            ]
        }
    ]
  }
}

dados array

Retorna um array de objetos Bina

SMS

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": "48111111111",
    "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":"48111111111","mensagem":"Ola tudo bem?"}' \
             'https://voice-api.zenvia.com/sms'

<?php
$client = new TotalVoiceClient('seu-token');
$response = $client->sms->enviar('48111111111', 'Ola tudo bem?');

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

client.sms.enviar("48111111111", "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("4811111111", "Ola tudo bem?", false, false, nil)

from totalvoice.cliente import Cliente

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.sms.enviar("48111111111", "Ola tudo bem?")

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

Sms sms = new Sms(client);
JSONObject response = sms.enviar("48111111111", "Ola tudo bem?");

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.sms.enviar("48111111111", "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":"48933445566",
      "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": "4899999999",
        "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": "4899999999",
        "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

TTS Leitura de Texto

TTS Endpoint

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

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

Assim, quando o número destino atende o mesmo irá escutar uma voz falando a mensagem que você escreveu.

Você poderá enviar algumas opções adicionais, tais como aguardar uma resposta do usuário, gravar o áudio da ligação ou colocar um número bina que aparecerá no momento da ligação.

Objeto TTS

JSON

{
    "id": 12345678,
    "numero_destino": "48912341234",
    "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": "+5548988888888",
    "chamada_verificada": true,
    "motivo_vcall": {
        "id": 123,
        "mensagem": "Texto do motivo"
    }
}

Definição do objeto TTS

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
chamada_verificada boolean	Se o tts foi enviado com chamada verificada
motivo_vcall objeto	Objeto do tipo Motivos VCall

¹ Após o usuário digitar algo no teclado númerico a ligação sera derrubada.

Criar um 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":"+554888881111", "bina": "+554811111111", "mensagem":"Olá", "chamada_verificada": true, "motivo_vcall": 57}' \
             '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('4811111111', 'Olá, essa é a minha mensagem');

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

client.tts.enviar("4811111111", "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("4811111111", "Olá, essa é a minha mensagem", false, "")

client = Cliente("seu-token", 'voice-api.zenvia.com')
response = client.tts.enviar("4811111111", "Olá, essa é a minha mensagem")

TotalVoiceClient client = new TotalVoiceClient("seu-token");
Tts tts = new Tts(client);

JSONObject response = tts.enviar("4811111111", "Olá, essa é a minha mensagem");

require 'totalvoice-ruby'
include TotalVoice

@client = TotalVoice::API.new("seu-token")
puts @client.tts.enviar("4811111111", "Olá, essa é a minha mensagem")

Response

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

Request

numero_destino Obrigatório	Número do telefone que irá receber a chamada, formato DDD + Número. Exemplo: 4832830151.
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 DDD + Número. Exemplo: 4832830151
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.
chamada_verificada Opcional	Um valor booleano para identificar se o tts terá chamada verificada
motivo_vcall Opcional	Id do motivo vcall da chamada verificada

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": "4832830151",
    "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": "+5548988888888",
    "chamada_verificada": true,
    "motivo_vcall": {
        "id": 123,
        "mensagem": "Texto do motivo"
    }
  }
}

Após o envio do TTS você poderá realizar a busca do registro pelo seu 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": "4832830151",
        "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": "+5548988888888",
        "chamada_verificada": true,
        "motivo_vcall": {
            "id": 123,
            "mensagem": "Texto do motivo"
        }
      },
      {
        "id": 13246578,
        "numero_destino": "4832830151",
        "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": "+5548988888888",
        "chamada_verificada": false,
        "motivo_vcall": {
            "id": null,
            "mensagem": null
        }
      }
    ]
  }
}

Você pode consultar os TTSs 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.
destino Opcional Query String	Número de destino da chamada.

Response

relatorio array

Retorna um array com objetos TTS

Exemplo: Se você tiver um relatório com 350 TTSs, na primeira página será retornado 200 TTSs. Para pegar os dados da segunda página o valor da posição deve ser 201.

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 depois 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.

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 um 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":"4811111111","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('4811111111', 'ZenAPI de Voz');

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

client.verificacao.enviar("4811111111", "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("4811111111", "ZenAPI de Voz", false, "")

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

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

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

require 'totalvoice-ruby'
include TotalVoice

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

Response

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

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 platarforma o código recebido para que você possa validar o número dele.

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'

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 na qual pode acessar o Webphone sem precisar se conectar a plataforma da ZenAPI, 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:

• Floating: Quando você vai abrir o Webphone em um popup;
• Embedded: Se o Webphone ficará embutido no site / sistema;
• 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

Consulta a URL do Webphone de um determinado Ramal enviando 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

Você pode criar um webphone utilizando 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

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.

Webhooks

Também conhecidos como Callbacks ou Reverse API, os Webhooks são notificações que enviamos para alguma URL (End Point) sua que é configurada no painel de Voz da ZenAPI, a notificação é enviada assim que determinados eventos acontecem.

Todos os Webhooks enviados vão por HTTP POST, sendo que as informações referentes ao evento vão no corpo da requisição em formato JSON.

Obs: Na requisição GET para visualizar os webhooks cadastrados ele irá trazer apenas os que possuem URL. Caso a conta seja uma subconta e não tiver URL de webhook, irá buscar os webhooks default configurados na conta principal.

Configuração

Entre no painel de Voz da ZenAPI com a conta administradora, vá até o menu Minha Conta e escolha Configurações da API, lá terão todos os campos para preencher em cada Webhook.

Poderá levar até 20 minutos após a configuração no Painel para começar o envio das notificações para o endereço escolhido.

Eventos em Tempo Real de Chamada

Sempre que uma das pernas de uma chamada muda de estado este webhook é enviado, entram nessas condições apenas ligações realizadas pela API e pelo Webphone/Softphone/Dispositivo de chamada conectado ao nosso sistema.

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": "48988888888",
    "status": "chamando"
  },
  "gravar_audio": false,
  "id": 37794869,
  "destino": {
    "tipo": "movel",
    "numero": "48966663333"
  },
  "cliente_id": 2150,
  "tags": ""
}

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.

Envio de SMS

Informa se o SMS foi enviado ou houve falha.

JSON

{
  "id": "37787430",
  "numero_destino": "48988888888",
  "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": []
}

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 DDD + Número. Exemplo: 4832830151.
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

Informa quando um usuário responde um SMS.

JSON

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

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

Eventos em Tempo Real de Ramal

A cada mudança de status de alguma chamada de algum Ramal, este Webhook é disparado, enviando os dados da chamada do 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
}

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

A cada mudança de status de alguma chamada recebida por um DID, este Webhook é disparado, enviando os dados da chamada e do Ramal que atendeu (se algum ramal atendeu).

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
}

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.

Aviso de saldo

Notifica quando o valor do saldo for inferior ao configurado no "Aviso de Saldo".

   {
   "saldo":"56.8616"
   }

Atributos

saldo float

Saldo atual da sua conta

Novo Voicemail

Notifica quando houver um novo voicemail / nova mensagem de voz na caixa postal.

  {
  "id": 1411,
  "ramal_id": 87787,
  "ramal": "9561",
  "numero_telefone": "6136271444",
  "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"
  }

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 DDD + Número. Exemplo: 4832830151.
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.

Eventos em Tempo Real de Conferências

A cada mudança dentro de uma conferência você recebe informações, quem entrou e quem saiu da conferência, id da chamada, id da conferência, número que entrou.

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

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

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 DDD + Número. Exemplo: 4832830151.
conferencia_id integer	Identificador único da conferência.
chamada_id String	Identificador único da chamada realizada para a conferência.

TTS Fim

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

JSON

{
  "id": 37784550,
  "numero_destino": "48988888888",
  "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"
}

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

Status Tempo Real

Durante uma chamada, este webhook é acionado sempre que o status mudar (de "chamando" para "atendido", por exemplo). Limitado em 1 request a cada 2s por chamada ativa.

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": "48988888888",
    "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": []
}

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

Fim Chamada

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

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": "48988888888",
    "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": []
}

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

DID Fim Chamada

Ao fim de toda chamada recebida(DID), um callback é feito para este endereço, enviando detalhes como duração e status.

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": "48988888888",
    "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": []
}

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 Chamada

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

JSON

{
  "id": 37850704,
  "numero_destino": "48988888888",
  "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"
}

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

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

JSON

{
  "id": 37785542,
  "numero_destino": "48988888888",
  "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"
}

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.