API DE ENVIO DE SMS

spacer
Disponibilizamos de uma API com todas as funções necessárias para você enviar e receber SMS de forma automática, rápida e segura direto de sua plataforma.

Apresentação

Integrando o IAGENTEsms ao seu sistema você pode realizar envios e recebimentos de torpedos de acordo com sua rotina de comunicação. Inclusive, é possível consultar os status de entrega através de uma chamada HTTP GET, confira.

Criando uma requisição HTTP

Parâmetros obrigatórios:

O consumo dos métodos através de requisições HTTP serão feitos através da URL abaixo. Importante lembrar que todos os parâmetros devem ser enviados no formato URLENCODE para evitar os caracteres reservados do protocolo.

https://www.iagentesms.com.br/webservices/http.php

A forma mais simples para realizar testes e saber se os parâmetros passados estão corretos é apenas colocar a url com todos os parâmetros na barra de endereço de seu navegador de Enter. O resultado da requisição será impresso na tela com sua mensagem de sucesso ou erro.

https://www.iagentesms.com.br/webservices/http.php?metodo=envio
&usuario=iagente
&senha=12345
&celular=5199999999
&mensagem=teste+integracao+http

Existem várias maneiras que permitem realizar estas requisições, onde a mais simples pode ser considerada a função nativa do próprio PHP, chamada de file_get_contents().

Exemplo de requisição:

$api_http = file_get_contents("
https://www.iagentesms.com.br/webservices/http.php?metodo=envio
&usuario=iagente
&senha=12345
&celular=5199999999
&mensagem=teste");
echo $api_http; // A resposta desta requisição será impressa na tela

Lembre-se de que requisições HTTP não interpretam alguns caracteres especiais/reservados e para isso utilize a função urlencode().

// codifica os dados no formato de um formulário www
$mensagem = urlencode("teste de requisicao http");

// concatena a url da api com a variável carregando o conteúdo da mensagem
$url_api = "https://www.iagentesms.com.br/webservices/http.php?metodo=envio
&usuario=iagente
&senha=12345
&celular=5199999999
&mensagem={$mensagem}";

// realiza a requisição http passando os parâmetros informados
$api_http = file_get_contents($url_api);

// imprime o resultado da requisição
echo $api_http;
?>

Outra informação importante é que requisições HTTP possuem tamanho máximo de caracteres. Este valor varia entre navegadores, caso a requisição seja feita por eles, e também varia entre servidores. Para o IAGENTEsms, o tamanho máximo de uma requisição HTTP é de 2.000 caracteres. Vale lembrar que este valor se refere apenas a requisições HTTP.

Consulta de saldo

Caso você possua sua conta na modalidade PRÉ-PAGA, é possível consultar o saldo da conta utilizando o método creditos.

Parâmetros obrigatórios:

Nome Exemplo Descrição
metodo creditos método para consultar saldo.
usuario iagente seu usuário de acesso ao sistema.
senha 12345 sua senha de acesso ao sistema.

Exemplo de requisição:

https://www.iagentesms.com.br/webservices/http.php?metodo=creditos
&usuario=iagente
&senha=12345

Envio de SMS individual

Parâmetros obrigatórios:

Importante lembrar que os parâmetros devem ser enviados no formato URL ENCODE.

Nome Exemplo Descrição
metodo envio método para envio de SMS individual sempre será "envio"
usuario iagente seu usuário de acesso ao sistema.
senha 12345 sua senha de acesso ao sistema.
celular 5199999999 telefone celular do destinatário com DDD
mensagem Teste de integracao conteudo do SMS

Parâmetros opcionais:

Nome Exemplo Descrição
data 10/10/2011 12:00:00 Data e hora para o agendamento da mensagem
codigosms 1 Identificador da mensagem em seu sistema

Exemplo de requisição:

https://www.iagentesms.com.br/webservices/http.php?metodo=envio
&usuario=iagente
&senha=1234
&celular=5199999999
&mensagem=teste

Após o envio de sua requisição a nossa plataforma uma resposta será devolvida, conforme tabela abaixo:

Códigos de retorno a sua requisição

Exemplo Descrição
OK Mensagem gravada na plataforma(sucesso)
ERRO – descricao do erro Mensagem de erro contendo descricao do erro

Envio de SMS em lote

Parâmetros obrigatórios:

Importante lembrar que os parâmetros devem ser enviados no formato URL ENCODE.

Nome Exemplo Descrição
metodo lote método para envio de SMS em lote sempre será "lote"
usuario iagente seu usuário de acesso ao sistema.
senha 12345 sua senha de acesso ao sistema.
celular 5199999999, 5199999998, ... listagem de celulares separados por vírgula (sem limite de números)
mensagem Teste de integracao conteúdo do SMS

Exemplo de requisição:

https://www.iagentesms.com.br/webservices/http.php?metodo=lote
&usuario=iagente
&senha=1234
&celular=5199999999,5188888888
&mensagem=teste

Após o envio de sua requisição a nossa plataforma uma resposta será devolvida, conforme tabela abaixo:

Códigos de retorno a sua requisição

Exemplo Descrição
OK Mensagem gravada na plataforma(sucesso)
ERRO – descricao do erro Mensagem de erro contendo descricao do erro

Consulta Status SMS

Parâmetros obrigatórios:

Nome Exemplo Descrição
metodo consulta método para consulta de status de SMS sempre será "consulta".
usuario iagente seu usuário de acesso ao sistema.
senha 12345 sua senha de acesso ao sistema.
codigosms 2023 identificador de mensagem em seu sistema ( apenas número inteiros - ex.: 2003).

Exemplo de requisição:

https://www.iagentesms.com.br/webservices/http.php?metodo=consulta
&usuario=iagente
&senha=1234
&codigosms=2023

Após o envio de sua requisição a nossa plataforma uma resposta será devolvida, conforme tabela abaixo:

Códigos de retorno a sua requisição

Resposta Descrição
AGUARDANDO Mensagem aguardando envio para operadora.
ENVIADO Mensagem enviada para operadora.
ENTREGUE Mensagem entregue ao destinatário.
NAO SUPORTADA Mensagem não suportada na plataforma.
NAO ENTREGAVEL Mensagem não vai ser entregue ao destinatário.
RECEBIDA Mensagem recebida por shortcode e Keyword (MO).
RESPOSTA Mensagem de resposta a uma mensagem previamente enviada (MO).
RECUSADA Mensagem recusada pela operadora.
FALHA OPERADORA Falha de envio da mensagem na operadora.
ERRO – descricao do erro Mensagem de falha contendo descrição do erro ao lado.

Call back de mensagens

A plataforma disponibiliza o envio automático de: ​

  • • Status de mensagens (todas as contas);
  • • Mensagens recebidas por keyword (canal corporativo);
  • • Respostas (canal corporativo).

Para receber essas informações em seu site ou sistema todas as mensagens devem ser identificadas, ou seja, devem conter seu próprio e único codigosms. Sendo assim o callback está disponível apenas para envios avulsos.

Exemplo:

https://www.iagentesms.com.br/webservices/http.php?metodo=envio
&usuario=iagente
&senha=1234
&celular=5199999999
&mensagem=teste
&codigosms=010
https://www.iagentesms.com.br/webservices/http.php?metodo=envio
&usuario=iagente
&senha=1234
&celular=5199998888
&mensagem=teste
&codigosms=020
https://www.iagentesms.com.br/webservices/http.php?metodo=envio
&usuario=iagente
&senha=1234
&celular=5199997777
&mensagem=teste
&codigosms=030
https://www.iagentesms.com.br/webservices/http.php?metodo=envio
&usuario=iagente
&senha=1234
&celular=5199996666
&mensagem=teste
&codigosms=040

Também é necessário configurar sua URL de retorno em seu painel web no menu "CONFIGURAÇÕES> INTEGRACAO" que deverá receber as requisições enviadas por nossa plataforma. Todas requisição são enviadas utilizando o método GET.

Exemplo de url para receber o call back:

http://www.seudominio.com.br/recebeSMS.php

Parâmetros enviados:

Parâmetro Utilização Descrição
codigosms Envio de status Identificador da mensagem em seu sistema
status Envio de status Texto com o status da mensagem (conforme códigos retorno envio de sms)
celular Recebimento de mensagem Número do celular que enviou a mensagem
shortcode Recebimento de mensagem Número shortcode que recebeu a mensagem
mensagem Recebimento de mensagem Resposta de um de seus destinatários a uma mensagem enviada

Instanciando método SOAP

O consumo de métodos do WEBSERVICE IAGENTEsms deve ser feito através da URL:

https://www.iagentesms.com.br/webservices/ws.php

Para instanciar um método SOAP você pode utilizar a classe nativa do PHP SoapClient, ao qual necessita de 2 parâmetros: A URI do arquivo WSDL e um array de opções.

Como a API da IAGENTEsms não utiliza modo WSDL, então é necessário informar um array de opções.

$options = array(
'location' => 'https://www.iagentesms.com.br/webservices/ws.php',
'uri' => 'https://www.iagentesms.com.br/webservices/',
'encoding' => 'ISO-8859-1',
'trace' => 1,
'exceptions'=> 0 );

Este array de opções deve ser passada como parâmetro para a classe SoapClient e armazená-la em uma variável.

$ws = new SoapClient(NULL, $options);

Desta maneira você estará pronto para consumir todos os métodos disponíveis em nossa API.

Para saber sobre mais como funciona o SoapClient e o parâmetro WSDL acesse:

  • http://php.net/manual/pt_BR/soapclient.soapclient.php
  • http://fabriciosanchez.com.br/2/wsdl-o-que-e-pra-que-serve-onde-utilizo/

Autenticação

Todos os métodos do WEBSERVICE só devem ser invocados após autenticação da conta, que pode ser feita uma única vez a cada sessão.

Para realizar a autenticação de sua conta através do método SOAP, é necessário utilizar o método Auth().

Parâmetros obrigatórios:

Nome Tipo Descrição
Usuário String Seu usuário de acesso ao sistema
Senha String Sua senha de acesso ao sistema

Exemplo de invocação do método:

$ws->Auth("iagente","1234");

Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.

Resposta a requisição

Campo Tipo Descrição
1 Boolean 1: OK, 0: FALHA
2 String Mensagem de falha ou sucesso

Consulta de saldo

Caso você possua sua conta na modalidade PRÉ-PAGA, é possível consultar o saldo da conta utilizando o método consulta_saldo().

Exemplo de invocação do método:

$ws->consulta_saldo();

Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.

http://www.seudominio.com.br/recebeSMS.php

Resposta a requisição consulta_saldo()

Nome Tipo Descrição
1 Boolean 1: OK, 0: FALHA
2 String Mensagem contendo saldo da conta

Criação de grupos

Para criar novos grupos em sua conta, utilize o método adicionar_grupo().

Parâmetros obrigatórios:

Nome Tipo Descrição
Grupo String Nome do grupo a ser criado

Exemplo de invocação do método:

$ws->adicionar_grupo("Novos clientes");

Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.

Resposta a requisição

Campo Tipo Descrição
1 Boolean 1: OK, 0: FALHA
2 String Mensagem de falha ou sucesso
3 Inteiro ID do grupo na conta do cliente

Atualização de grupos

Para renomear um grupo é necessário utilizar o método atualizar_grupo().

Parâmetros obrigatórios

Nome Tipo Descrição
ID_GRUPO Inteiro ID do grupo de sua conta
Grupo String Novo nome do grupo

Exemplo de invocação do método:

$ws->atualizar_grupo("739", "Clientes antigos");

Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.

http://www.seudominio.com.br/recebeSMS.php

Resposta a requisição

Campo Tipo Descrição
1 Boolean 1: OK, 0: FALHA
2 String Mensagem de falha ou sucesso

Listagem de grupos

Para listar todos os grupos de sua conta, utilize o método listar_grupos().

Exemplo de invocação do método:

$ws->listar_grupos();

Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.

Resposta a requisição

Campo Tipo Descrição
1 Matriz Matriz com informações dos grupos

Remover grupo

Para remover um grupo de sua conta, utilize o método remover_grupo().

Parâmetros obrigatórios:

Nome Tipo Descrição
ID_GRUPO Inteiro ID do grupo na conta do cliente

Exemplo de invocação do método:

$ws->remover_grupo("739");

Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.

Resposta a requisição

Campo Tipo Descrição
1 Boolean 1: OK, 0: FALHA
2 String Mensagem de falha ou sucesso

Inserir contato no grupo

Para adicionar um contato a um grupo, utilize o método adicionar_contato().

Parâmetros disponíveis

Nome Tipo Descrição
Nome String Nome do contato
Celular Inteiro Número de celular do contato, com DDD
ID_GRUPO Inteiro ID do grupo em sua conta

Exemplo de invocação do método:

$ws->adicionar_contato("João","5199999999","739");

Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.

Resposta a requisição

Campo Tipo Descrição
1 Boolean 1: OK, 0: FALHA
2 String Mensagem de falha ou sucesso

Remover contato do grupo

Para remover um contato de algum grupo, utilize o método remover_contato().

Parâmetros obrigatórios:

Nome Tipo Descrição
Celular Inteiro Número de celular do contato, com DDD
ID_GRUPO Inteiro ID do grupo em sua conta

Exemplo de invocação do método:

$ws->remover_contato("5199999999","739");

Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.

Resposta a requisição

Campo Tipo Descrição
1 Boolean 1: OK, 0: FALHA
2 String Mensagem de falha ou sucesso

Excluir contatos dos grupos

Para remover todos os contatos de um grupo, utilize o método limpar_grupo().

Parâmetros obrigatórios:

Nome Tipo Descrição
ID_GRUPO Inteiro ID do grupo em sua conta

Exemplo de invocação do método:

$ws->limpar_grupo("739");

Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.

Resposta a requisição

Campo Tipo Descrição
1 Boolean 1: OK, 0: FALHA
2 String Mensagem de falha ou sucesso

Envio de mensagem avulsa

Para enviar uma mensagem utilizando o método SOAP, utilize o método enviar_sms().

Parâmetros disponíveis

Nome Tipo Descrição
Método String Método para envio avulso sempre será "avulso"
Destinatário Inteiro Número de destino com DDD
Mensagem String Mensagem com até 150 caracteres
Data Data e Hora Data do envio - opcional
Código Inteiro Código interno do cliente para consulta de Postback - opcional

Exemplo de invocação do método:

$ws->enviar_sms("avulso", "5199999999", "Teste de SMS", "", "2034");

Apesar do parâmetro Código ser opcional vale lembrar que, caso não seja passado, futuramente não será possível realizar a consulta de status deste envio.

Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.

Resposta a requisição

Campo Tipo Descrição
1 Boolean 1: OK, 0: FALHA
2 String Mensagem de falha ou sucesso
3 Inteiro ID do agendamento

Envio de mensagens em lote

Para enviar mensagens em lote, utilize o método enviar_lote().

Parâmetros disponíveis

Nome Tipo Descrição
Método String Método para envio em lote sempre será "lote"
Destinatários Array Números de destino com DDD
Mensagem String Mensagem com até 150 caracteres
Data Data e Hora Data do envio - opcional

Exemplo de invocação do método:

$ws->enviar_lote("lote", array("5199999999","5198888888","5197777777"), "Teste de SMS", "", "2034");

Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.

Resposta a requisição

Campo Tipo Descrição
1 Boolean 1: OK, 0: FALHA
2 String Mensagem de falha ou sucesso
3 Inteiro ID do agendamento

Envio de mensagem para grupo

Para enviar mensagem para um grupo de sua conta, utilize o método enviar_sms_grupo().

Parâmetros disponíveis

Nome Tipo Descrição
Método String Método para envio em grupo sempre será "grupo"
Grupo Inteiro ID do grupo em sua conta
Mensagem String Mensagem com até 150 caracteres
Data Data e Hora Data do envio - opcional
Código Inteiro Código interno de seu envio para consulta de Postback

Exemplo de invocação do método:

$ws->enviar_sms_grupo("grupo", "739", "Teste de SMS", "", "1020");

Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.

Resposta a requisição

Campo Tipo Descrição
1 Boolean 1: OK, 0: FALHA
2 String Mensagem de falha ou sucesso
3 Inteiro ID do agendamento

Consulta Status SMS: * Função disponível apenas para envio de SMS individuais

Para consultar o status de um SMS enviado, utilize o método verifica_status().

Parâmetros disponíveis

Nome Tipo Descrição
ID_AGENDAMENTO Inteiro ID do cliente informado na invocação do método enviar_sms().

Exemplo de invocação do método:

$ws->verifica_status("1020");

Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.

Resposta a requisição

Campo Tipo Descrição
1 Boolean 1: OK, 0: FALHA
2 String Mensagem de falha ou sucesso

Códigos de retorno a sua requisição

Resposta Descrição
AGUARDANDO Mensagem aguardando envio para operadora.
ENVIADO Mensagem enviada para operadora.
ENTREGUE Mensagem entregue ao destinatário.
NAO SUPORTADA Mensagem não suportada na plataforma.
NAO ENTREGAVEL Mensagem não vai ser entregue ao destinatário.
RECEBIDA Mensagem recebida por shortcode e Keyword (MO).
RESPOSTA Mensagem de resposta a uma mensagem previamente enviada (MO).
RECUSADA Mensagem recusada pela operadora.
FALHA OPERADORA Falha de envio da mensagem na operadora.
ERRO – descricao do erro Mensagem de falha contendo descrição do erro ao lado.

Call back de mensagens

A plataforma disponibiliza o envio automático de: ​

  • • Status de mensagens (todas as contas);
  • • Mensagens recebidas por keyword (canal corporativo);
  • • Respostas (canal corporativo).

Para receber essas informações em seu site ou sistema informe uma URL em seu painel web no menu "CONFIGURAÇÕES> INTEGRACAO" que deverá receber as requisições enviadas por nossa plataforma. Todas requisição são enviadas utilizando o método GET.

Exemplo de url para receber o call back:

http://www.seudominio.com.br/recebeSMS.php

Parâmetros enviados no Call Back de mensagens:

Parâmetro Utilização Descrição
codigosms Envio de status Identificador da mensagem em seu sistema
status Envio de status Texto com o status da mensagem (conforme códigos retorno envio de sms)
celular Recebimento de mensagem Número do celular que enviou a mensagem
shortcode Recebimento de mensagem Número shortcode que recebeu a mensagem
mensagem Recebimento de mensagem Resposta de um de seus destinatários a uma mensagem enviada

Transformando e-mail em SMS

É possível realizar envios de SMS através de email (smtp). Basta o email do remetente estar cadastrado como usuário no sistema.

O email deve ser enviado para @api.iagentesms.com.br com o celular antes do @.

Exemplos:

5199999999@api.iagentesms.com.br
5199999999-5188888888-5177777777@api.iagentesms.com.br

Após o envio da requisição, o IAGENTEsms devolverá uma resposta em formato de vetor (array), conforme abaixo.

O conteúdo do SMS será o assunto ou o texto do email. Caso ambos tenham sido informados, os conteúdos serão unidos e enviados os primeiros 150 caracteres.

Aplicações:

De: ti@iagente.com.br
Para: 5199999999@api.iagentesms.com.br
Assunto: Todos os serviços foram reestabelecidos
De: ti@iagente.com.br
Para: 5199999999-5188888888@api.iagentesms.com.br
Assunto:
Mensagem: Reunião adiada para o próximo dia 15

Cadastrando novos remetentes

Para realizar envios de SMS através de SMTP, é preciso que o email do remetente esteja cadastrado em sua conta como um usuário.

Para cadastrar um novo usuário como remetente, acesse o menu de configurações de sua e clique em Usuários

Após isso basta envia um email a partir desta conta para nossa api que a mensagem será automaticamente convertida em um SMS..

Exemplo:

De: ti@iagente.com.br
Para: 5199999999@api.iagentesms.com.br
Assunto: Todos os serviços foram reestabelecidos.

ASSINE NOSSA NEWSLETTER

Rua Açores, nº 68, conjunto 501, Passo D'Areia - Porto Alegre - RS - Brasil - CEP 91030-340
4007.2564 - Capitais e regiões metropolitanas
(51) 3119.2600 - Demais localidades