TTS (Text-to-Speech) API Web Service

Versão: 3.00 Última Atualização: 06/08/2015


Índice

  1. Introdução
  2. Realizando chamadas de voz com TTS (Text-to-Speech)
  3. Obtendo o saldo de créditos em conta
  4. Consultando envios realizados em um determinado período
  5. Consultando o status da chamada de Voz
  6. 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.

O conteúdo da mensagem deve ter no máximo 350 posições. Este número representa cerca de 30 segundos de vocalização.

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
“V-PTBR-F1” = Feminino

Inglês dos EUA, utilize:

“V-ENUS-M1” = Masculino
“V-ENUS-F1” = Feminino

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

Em caso de sucesso o retorno é XXX:IDMPG, sendo XXX sempre igual a 000. Em caso de Erro o retorno pode ser: XXX ou XXX:IDERR, sendo XXX o código de erro.

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.

Créditos são utilizados para enviar qualquer tipo de mensagem e podem ser adquiridos em nossa “Loja Virtual” através da plataforma.

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.

O retorno é um XML de até 1000 linhas, no qual os campos são: código auxiliar, data de envio, mobile, flag de recebimento, código de retorno e message.

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>';
?>