API

Disponibilizamos de uma API com todas as funções necessárias para que 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:
http-criando-uma-requisicao-http
O consumo dos métodos através de requisições HTTP são todas feitas através da url:
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 espaçamento entre as palavras de sua mensagem. 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.

Criando uma requisição HTTP

Parâmetros obrigatórios:
http-criando-uma-requisicao-http
O consumo dos métodos através de requisições HTTP são todas feitas através da url:
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 espaçamento entre as palavras de sua mensagem. 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.

Envio de SMS individual

Parâmetros obrigatórios:
Nome
  • metodo
  • usuario
  • senha
  • celular
  • mensagem
Exemplo
  • envio
  • iagente
  • 12345
  • 5199999999
  • Teste de integracao
Descrição
  • método para envio de SMS individual sempre será "envio"
  • seu usuário de acesso no sistema
  • sua senha de acesso ao sistema
  • telefone celular do destinatário com DDD
  • conteudo do SMS
Parâmetros opcionais:
Nome
  • data
  • codigosms
Exemplo
  • 10/10/2011 12:00:00
  • 1
Descrição
  • Data e hora para o agendamento da mensagem
  • 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
  • OK
  • ERRO – descricao do erro
Descrição
  • Mensagem gravada na plataforma(sucesso)
  • Mensagem de erro contendo descricao do erro

Envio de SMS em lote

Parâmetros obrigatórios:
Nome
  • metodo
  • usuario
  • senha
  • celulares
  • mensagem
Exemplo
  • lote
  • iagente
  • 12345
  • 5199999999, 5199999998, ...
  • Teste de integracao
Descrição
  • método para envio de SMS em lote sempre será "lote"
  • seu usuário de acesso no sistema.
  • sua senha de acesso ao sistema.
  • listagem de celulares separados por vírgula (sem limite de números)
  • 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
Resposta
  • OK
  • ERRO – descricao do erro
Descrição
  • Mensagem gravada na plataforma(sucesso)
  • Mensagem de erro contendo descricao do erro

Consulta Status SMS

Parâmetros obrigatórios:
Nome
  • metodo
  • usuario
  • senha
  • codigosms
Exemplo
  • consulta
  • iagente
  • 12345
  • 2023
Descrição
  • método para consulta de status de SMS sempre será "consulta".
  • seu usuário de acesso no sistema.
  • sua senha de acesso ao sistema.
  • 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
  • AGUARDANDO
  • ENVIADO
  • ENTREGUE
  • NAO SUPORTADA
  • NAO ENTREGAVEL
  • RECEBIDA
  • RESPOSTA
  • RECUSADA
  • FALHA OPERADORA
  • ERRO – descricao do erro
Descrição
  • Mensagem aguardando envio para operadora.
  • Mensagem enviada para operadora.
  • Mensagem entregue ao destinatário.
  • Mensagem não suportada na plataforma.
  • Mensagem não vai ser entregue ao destinatário.
  • Mensagem recebida por shortcode e Keyword (MO).
  • Mensagem de resposta a uma mensagem previamente enviada (MO).
  • Mensagem recusada pela operadora.
  • Falha de envio da mensagem na operadora.
  • 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
  • codigosms
  • status
  • celular
  • shortcode
  • mensagem
Utilização
  • Envio de status
  • Envio de status
  • Recebimento de mensagem
  • Recebimento de mensagem
  • Recebimento de mensagem
Descrição
  • Identificador da mensagem em seu sistema
  • Texto com o status da mensagem (conforme códigos retorno envio de sms)
  • Número do celular que enviou a mensagem
  • Número shortcode que recebeu a 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
  • Usuário
  • Senha
Tipo
  • String
  • String
Descrição
  • Seu usuário de acesso ao sistema
  • 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
  • 1
  • 2
Tipo
  • Boolean
  • String
Descrição
  • 1: OK, 0: FALHA
  • 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()
Campo
  • 1
  • 2
Tipo
  • Boolean
  • String
Descrição
  • 1: OK, 0: FALHA
  • 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
  • Grupo
Tipo
  • String
Descrição
  • 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
  • 1
  • 2
  • 3
Tipo
  • Boolean
  • String
  • Inteiro
Descrição
  • 1: OK, 0: FALHA
  • Mensagem de falha ou sucesso
  • 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
  • ID_GRUPO
  • Grupo
Tipo
  • Inteiro
  • String
Descrição
  • ID do grupo de sua conta
  • 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
  • 1
  • 2
Tipo
  • Boolean
  • String
Descrição
  • 1: OK, 0: FALHA
  • 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
  • 1
Tipo
  • Matriz
Descrição
  • 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
  • ID_GRUPO
Tipo
  • Inteiro
Descrição
  • 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
  • 1
  • 2
Tipo
  • Boolean
  • String
Descrição
  • 1: OK, 0: FALHA
  • 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
  • Nome
  • Celular
  • ID_GRUPO
Tipo
  • String
  • Inteiro
  • Inteiro
Descrição
  • Nome do contato
  • Número de celular do contato, com DDD
  • 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
  • 1
  • 2
Tipo
  • Boolean
  • String
Descrição
  • 1: OK, 0: FALHA
  • 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
  • Celular
  • ID_GRUPO
Tipo
  • Inteiro
  • Inteiro
Descrição
  • Número de celular do contato com DDD
  • 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
  • 1
  • 2
Tipo
  • Boolean
  • String
Descrição
  • 1: OK, 0: FALHA
  • 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
  • ID_GRUPO
Tipo
  • Inteiro
Descrição
  • 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
  • 1
  • 2
Tipo
  • Boolean
  • String
Descrição
  • 1: OK, 0: FALHA
  • 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
  • Método
  • Destinatário
  • Mensagem
  • Data
  • Código
Tipo
  • String
  • Inteiro
  • String
  • Data e Hora
  • Inteiro
Descrição
  • Método para envio avulso sempre será "avulso"
  • Número de destino com DDD
  • Mensagem com até 150 caracteres
  • Data do envio - opcional
  • 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 respost a em formato de vetor (array), conforme abaixo.
Resposta a requisição
Campo
  • 1
  • 2
  • 3
Tipo
  • Boolean
  • String
  • Inteiro
Descrição
  • 1: OK, 0: FALHA
  • Mensagem de falha ou sucesso
  • ID do agendamento

Envio de mensagens em lote

Para enviar mensagens em lote, utilize o método enviar_lote().
Parâmetros disponíveis:
Nome
  • Método
  • Destinatários
  • Mensagem
  • Data
  • Código
Tipo
  • String
  • Array
  • String
  • Data e Hora
  • Inteiro
Descrição
  • Método para envio em lote sempre será "lote"
  • Números de destino com DDD
  • Mensagem com até 150 caracteres
  • Data do envio - opcional
  • Código interno de seu envio para consulta de Postback
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
  • 1
  • 2
  • 3
Tipo
  • Boolean
  • String
  • Inteiro
Descrição
  • 1: OK, 0: FALHA
  • Mensagem de falha ou sucesso
  • 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
  • Método
  • Grupo
  • Mensagem
  • Data
  • Código
Tipo
  • String
  • Inteiro
  • String
  • Data e Hora
  • Inteiro
Descrição
  • Método para envio em grupo sempre será "grupo"
  • ID do grupo em sua conta
  • Mensagem com até 150 caracteres
  • Data do envio - opcional
  • 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
  • 1
  • 2
  • 3
Tipo
  • Boolean
  • String
  • Inteiro
Descrição
  • 1: OK, 0: FALHA
  • Mensagem de falha ou sucesso
  • 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
  • ID_AGENDAMENTO
Tipo
  • Inteiro
Descrição
  • 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
  • 1
  • 2
Tipo
  • Boolean
  • String
Descrição
  • 1: OK, 0: FALHA
  • Status da mensagem
Códigos de retorno a sua requisição
Resposta
  • AGUARDANDO
  • ENVIADO
  • ENTREGUE
  • NAO SUPORTADA
  • NAO ENTREGAVEL
  • RECEBIDA
  • RESPOSTA
  • RECUSADA
  • FALHA OPERADORA
  • ERRO – descricao do erro
Tipo
  • Mensagem aguardando envio para operadora
  • Mensagem enviada para operadora
  • Mensagem entregue ao destinatário
  • Mensagem nao suportada na plataforma
  • Mensagem nao vai ser entregue ao destinatario
  • Mensagem recebida por shortcode e Keyword (MO)
  • Mensagem de resposta a uma mensagem previamente enviada (MO)
  • Mensagem recusada pela operadora
  • Falha de envio da mensagem na operadora
  • Mensagem de erro contendo descricao 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
  • codigosms
  • status
  • celular
  • shortcode
  • mensagem
Utilização
  • Envio de status
  • Envio de status
  • Recebimento de mensagem
  • Recebimento de mensagem
  • Recebimento de mensagem
Descrição
  • Identificador da mensagem em seu sistema
  • Texto com o status da mensagem (conforme códigos retorno envio de sms)
  • Número do celular que enviou a mensagem
  • Número shortcode que recebeu a 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.