Versão: 3.00 Última Atualização: 06/08/2015
Índice
- Introdução
- Realizando chamadas de voz com TTS (Text-to-Speech)
- Obtendo o saldo de créditos em conta
- Consultando envios realizados em um determinado período
- Consultando o status da chamada de Voz
- Exemplo em PHP
1. Introdução
Seguindo a documentação presente nesta página, você irá conseguir integrar o seu sistema com o Gateway de Text-to-Speech do PitchWink! Para começar de pé direito, sugerimos que você leia os requerimentos, as notas importantes (onde comunicamos novidades e mudanças futuras) e as descrições de cada método. Desta forma, você irá ganhar tempo e conhecer a solução como um todo. Em caso de dúvida, estamos aqui para ajudá-lo! Acesse sua conta, crie um ticket de suporte e entre em contato conosco. Divirta-se integrando!
1.1. Requerimentos
É necessário ter acesso a “Credencial” e “Token” da sua conta para realizar a integração. Estes dados podem ser encontrados no menu de “Configurações”, opção “Dados de Integração”.
1.2. URL do Web Service
http://pw-api.com/voice/v_3_00/service.asmx
1.3. Notas importantes
1 A próxima versão irá contar com novos idiomas e vocalizações!
2 O seguinte método será descontinuado
- MPG_Send_Voice
Utilize o novo método MPG_SendandFollowUp_Voice para enviar mensagens de voz.
2. Realizando chamadas de voz com TTS (Text-to-Speech)
O MPG_SendandFollowUp_Voice é o método que permite o envio de mensagens de voz utilizando a tecnologia de vocalização de texto, chamada TTS (Text-to-Speech), através do nosso Gateway.
2.1. Parâmetros do MPG_SendandFollowUp_Voice
Parâmetro | Requerido? | Formato | Descrição |
---|---|---|---|
CREDENCIAL | Sim | A(40) | Credencial da sua conta no PitchWink |
TOKEN | Sim | A(6) | Código de acesso ao Gateway |
PRINCIPAL_USER | Sim | A(50) ou “” | Controle interno do cliente |
AUX_USER | Sim | A(20) | O valor atribuído a este parâmetro pode ser utilizado como referência em filtros, facilitando a identificação de mensagens específicas em relatórios criados por você a partir da plataforma |
MOBILE | Sim | A(15) | Número do telefone celular ou fixo do destinatário em formato internacional. Exemplo para o Brasil: +55(21)999999999 |
VOICE | Sim | A(9) | O idioma e tipo de vocalização.
Português do Brasil, utilize: “V-PTBR-M1” = Masculino ou Inglês dos EUA, utilize: “V-ENUS-M1” = Masculino |
MESSAGE | Sim | A(350) | Conteúdo da mensagem que será vocalizada em TTS e consequentemente enviada ao destinatário. |
2.2. Retornos do MPG_SendandFollowUp_Voice
Código de Retorno | Tipo | Descrição |
---|---|---|
000 | Sucesso | Mensagem enviada com sucesso |
001 | Erro | Credencial inválida |
005 | Erro | Telefone com formato inválido |
008 | Erro | Conteúdo da mensagem com número de posições excedidas no país de destino |
009 | Erro | Créditos insuficientes em conta |
010 | Erro | Gateway da conta bloqueado |
012 | Erro | Telefone correto, porém com crítica |
013 | Erro | Conteúdo da mensagem inválido ou vazio |
015 | Erro | País sem cobertura |
016 | Erro | Telefone com código de área inválido |
017 | Erro | Operadora não autorizada para esta credencial |
018 | Erro | Telefone se encontra em lista negra |
019 | Erro | Token inválido |
020 | Erro | Voz inválida |
021 | Erro | Telefone está na lista negra do orgão de comunicação responsável do país |
800 a 899 | Erro | Falha no Gateway |
900 | Erro | Erro de autenticação ou limite de segurança excedido |
901 a 999 | Erro | Erro no acesso as operadoras |
3. Obtendo o saldo de créditos em conta
O método MPG_Credits serve para consultar o número de créditos disponíveis em sua conta.
3.1. Parâmetros do MPG_Credits
Parâmetro | Requerido? | Formato | Descrição |
---|---|---|---|
CREDENCIAL | Sim | A(40) | Credencial da sua conta no PitchWink |
TOKEN | Sim | A(6) | Código de acesso ao Gateway |
STATUS | Sim | A(3) | Caso preenchido vêm com o código de erro |
3.2. Retornos do MPG_Credits
Código de Retorno | Tipo | Descrição |
---|---|---|
N. DE CRÉDITOS | Sucesso | O número de créditos disponível em sua conta. Este retorno contém 5 casas decimais. Ex: 855357,20000. Em caso de erro, o retorno será -1 e no campo STATUS, irá conter um dos erros abaixo. |
001 | Erro | Credencial inválida |
019 | Erro | Token inválido |
800 a 899 | Erro | Falha no Gateway |
900 | Erro | Erro de autenticação ou limite de segurança excedido |
901 a 999 | Erro | Erro no acesso as operadoras |
4. Consultando envios realizados em um determinado período
O método MPG_Query01 é utilizado para consultar as mensagens enviadas através da sua conta em um determinado intervalo de tempo.
4.1. Parâmetros do MPG_Query01
Parâmetro | Requerido? | Formato | Descrição |
---|---|---|---|
CREDENCIAL | Sim | A(40) | Credencial da sua conta no PitchWink |
TOKEN | Sim | A(6) | Código de acesso ao Gateway |
START_DATE | Sim | A(10) | Data inicial da consulta. Ex: 14/07/2017 |
END_DATE | Sim | A(10) | Data final da consulta. Ex: 15/07/2017 |
AUX_USER | Sim | A(20) | O valor atribuído a este parâmetro pode ser utilizado como referência em filtros, facilitando a identificação de mensagens específicas em relatórios criados por você a partir da plataforma |
MOBILE | Sim | A(15) | Número telefônico do destinatário em formato internacional. Exemplo para o Brasil: +55(21)999999999 |
STATUS_CODE | Sim | N | 0 – Enviado com erro de crítica 1 – Enviado com sucesso 2 – Ambos |
4.2. Retornos do MPG_Query01
Código de Retorno | Tipo | Descrição |
---|---|---|
XML | Sucesso | XML com os resultados solicitados (máximo de 1000 linhas). Os campos incluem: código auxiliar, data de envio, mobile, flag de recebimento, código de retorno e message |
001 | Erro | Credencial inválida |
002 | Erro | Data inicial inválida |
003 | Erro | Data final inválida |
005 | Erro | Telefone com formato inválido |
019 | Erro | Token inválido |
890 | Erro | Falha no método MPG_Query01, favor entrar em contato com o suporte |
5. Consultando o Status da chamada de Voz
O método MPG_Status_Voice é utilizado para consultar o status da chamda de voz.
5.1. Parâmetros do MPG_Status_Voice
Parâmetro | Requerido? | Formato | Descrição |
---|---|---|---|
CREDENCIAL | Sim | A(40) | Credencial da sua conta no PitchWink |
TOKEN | Sim | A(6) | Código de acesso ao Gateway |
IDMSG | Sim | A(40) | Chave da mensagem de voz enviada (vide MPG_SendandFollowUp_Voice) |
5.2. Retornos com Erro
Código de Retorno | Tipo | Descrição |
---|---|---|
001 | Erro | Credencial inválida |
019 | Erro | Token inválido |
022 | Erro | Conta do Mobi Pronto não encontrada |
023 | Erro | IDMSG de Voz não encontrado |
024 | Erro | IDMSG ainda sem Status de Voz ou Status não gerado |
800 a 899 | Erro | Falha no Gateway |
900 | Erro | Erro de autenticação ou limite de segurança excedido |
901 a 999 | Erro | Erro no acesso as operadoras |
5.3. Tipos de Status (caso existente)
SIP – Session Initiation Protocol. Favor verificar os possíveis status através da Wikipedia, através deste link http://en.wikipedia.org/wiki/List_of_SIP_response_codes
Código de Retorno | Descrição |
---|---|
ok:999 | Mensagem enviada com sucesso e a duração da mesma em segundos. |
failed:XXX | Falha na chamada e o código SIP |
error:XXX | Erro durante a chamada e o código SIP |
blocked:XXX | Chamada bloqueada e o código SIP |
machine:XXX | Chamada parou ao se detectar alguma máquina ao se fazer a chamada e o código SIP. Ex: secretária eletrônica). |
6. Exemplo em PHP
<?php ini_set("max_execution_time", 3600); //require_once('intscripttopo.php'); $datahoje = date('Y-m-d'); require_once('dist/nusoap/lib/nusoap.php'); //require_once('lib/nusoap.php'); $proxyhost = isset($_POST['proxyhost']) ? $_POST['proxyhost'] : ''; $proxyport = isset($_POST['proxyport']) ? $_POST['proxyport'] : ''; $proxyusername = isset($_POST['proxyusername']) ? $_POST['proxyusername'] : ''; $proxypassword = isset($_POST['proxypassword']) ? $_POST['proxypassword'] : ''; // WEBSERVICE VOZ $client = new nusoap_client('http://www.pw-api.com/v_3_00/voice/service.asmx?wsdl', true, $proxyhost, $proxyport, $proxyusername, $proxypassword); // WEBSERVICE SMS //$client = new nusoap_client('http://www.pw-api.com/v_3_00/sms/service.asmx?wsdl', true, $proxyhost, $proxyport, $proxyusername, $proxypassword); $err = $client->getError(); if ($err) { echo '<h2>Erro do construtor</h2><pre>' . $err . '</pre>'; } // $param = array( 'Credencial' => 'XXXXXXXXXXUUUUUUUUUUTTTTTTTTTTRRRRRRRRRR', 'Token' => 'sertgu', 'Principal_User' => 'XX', 'Aux_User' => '123456', 'Mobile' => '+55(21)999999999', 'Voice' => 'V-PTBR-M1', 'Message' => 'Oi, esta é uma mensagem de Voz.' ); $result = $client->call('MPG_SendandFollowUp_Voice', array('parameters' => $param), '', '', false, true); utf8_encode($result); echo $result['MPG_SendandFollowUp_VoiceResult']; // 000:MPG000117875432 $aux = explode(':', $result['MPG_SendandFollowUp_VoiceResult']); $codstatus = $aux[0]; $codigo = $aux[1]; ############################################# ########## ANALISE DE ERRO E DEBUG ########## ############################################# // Check for a fault if ($client->fault) { echo '<h2>Fault</h2><pre>'; print_r($result); echo '</pre>'; } else { // Verificando Erros $err = $client->getError(); if ($err) { // Apresentando Erros echo '<h2>Error</h2><pre>' . $err . '</pre>'; } else { // Apresentando Resultado echo '<h2>Result</h2><pre>'; print_r($result); echo '</pre>'; } } echo '<h2>Request</h2><pre>' . htmlspecialchars($client->request, ENT_QUOTES) . '</pre>'; echo '<h2>Response</h2><pre>' . htmlspecialchars($client->response, ENT_QUOTES) . '</pre>'; echo '<h2>Debug</h2><pre>' . htmlspecialchars($client->debug_str, ENT_QUOTES) . '</pre>'; ?>