Documentação API SMS

API SMS IAGENTEsms — envio de SMS via HTTP e SOAP

API de envio de SMS para Brasil. Envio individual e em lote, callback de entrega, consulta de status e SMS interativo via HTTP, SOAP e SMTP. Exemplos em cURL, PHP e Python.

API HTTP

A API HTTP é a forma mais simples de integrar o envio de SMS ao seu sistema. Todas as requisições são feitas via GET ou POST para a URL base.

Base URL

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

Autenticação

Todas as requisições devem incluir os parâmetros usuario e senha fornecidos no painel do IAGENTEsms.

Consulta de Créditos

GET /webservices/http.php?metodo=creditos Consultar saldo

Retorna o saldo de créditos disponível na conta.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
metodo string Sim Valor fixo: créditos
usuario string Sim Usuário da conta
senha string Sim Senha da conta

Exemplos

https://api.iagentesms.com.br/webservices/http.php?metodo=creditos&usuario=SEU_USUARIO&senha=SUA_SENHA
curl "https://api.iagentesms.com.br/webservices/http.php?metodo=creditos&usuario=SEU_USUARIO&senha=SUA_SENHA"
<?php
$params = [
    'metodo'  => 'creditos',
    'usuario' => 'SEU_USUARIO',
    'senha'   => 'SUA_SENHA'
];

$url = 'https://api.iagentesms.com.br/webservices/http.php?' . http_build_query($params);

$response = file_get_contents($url);
echo $response;
// Sucesso: "CREDITOS: 1500"
?>
Códigos de Resposta
Resposta Descrição
CREDITOS: 1500 Saldo atual de créditos
ERROR 01 Usuário ou senha inválidos
ERROR 99 Erro interno do servidor

Envio Individual

GET /webservices/http.php?metodo=envio Enviar SMS individual

Envia um SMS individual para um número de celular.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
metodo string Sim Valor fixo: envio
usuario string Sim Usuário da conta
senha string Sim Senha da conta
celular string Sim Número do celular com DDD (ex: 5551999999999)
mensagem string Sim Texto da mensagem (máx. 160 caracteres por SMS)
agendamento string Não Data/hora para envio agendado no formato DD/MM/AAAA HH:MM
codigosms string Não Código alfanumérico para uso interno do cliente (ex: 123456X3), utilizado no envio de CALLBACK.

Exemplos

https://api.iagentesms.com.br/webservices/http.php?metodo=envio&usuario=SEU_USUARIO&senha=SUA_SENHA&celular=5551999999999&mensagem=Ola!+Este+e+um+teste.
curl "https://api.iagentesms.com.br/webservices/http.php?metodo=envio&usuario=SEU_USUARIO&senha=SUA_SENHA&celular=5551999999999&mensagem=Ola!+Este+e+um+teste."
<?php
$params = [
    'metodo'   => 'envio',
    'usuario'  => 'SEU_USUARIO',
    'senha'    => 'SUA_SENHA',
    'celular'  => '5551999999999',
    'mensagem' => 'Olá! Este é um SMS de teste via API.'
];

$url = 'https://api.iagentesms.com.br/webservices/http.php?' . http_build_query($params);

$response = file_get_contents($url);
echo $response;
// Sucesso: "OK 123456"
// Erro: "ERROR 03"
?>
Códigos de Resposta
Código Descrição
OK Envio realizado com sucesso
ERROR 01 Usuário ou senha inválidos
ERROR 02 Créditos insuficientes
ERROR 03 Número de celular inválido
ERROR 04 Mensagem vazia
ERROR 05 Mensagem muito longa
ERROR 06 Data de agendamento inválida
ERROR 99 Erro interno do servidor

Envio em Lote

POST /webservices/http.php?metodo=lote Enviar SMS em lote

Envia SMS para múltiplos números de uma vez. Os números e mensagens devem ser enviados separados por ponto e vírgula.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
metodo string Sim Valor fixo: lote
usuario string Sim Usuário da conta
senha string Sim Senha da conta
celulares string Sim Números separados por ; (ex: 5551999999999;5551888888888)
mensagens string Sim Mensagens separadas por ;. Se for fornecida uma única mensagem, ela será enviada para todos os números.
agendamento string Não Data/hora para envio agendado no formato DD/MM/AAAA HH:MM

Exemplos

curl -X POST "https://api.iagentesms.com.br/webservices/http.php" \
  -d "metodo=lote" \
  -d "usuario=SEU_USUARIO" \
  -d "senha=SUA_SENHA" \
  -d "celulares=5551999999999;5551888888888;5551777777777" \
  -d "mensagens=Olá João!;Olá Maria!;Olá Pedro!"
curl -X POST "https://api.iagentesms.com.br/webservices/http.php" \
  -d "metodo=lote" \
  -d "usuario=SEU_USUARIO" \
  -d "senha=SUA_SENHA" \
  -d "celulares=5551999999999;5551888888888;5551777777777" \
  -d "mensagens=Promoção especial! Desconto de 20%% em todos os produtos."
<?php
$url = 'https://api.iagentesms.com.br/webservices/http.php';

$data = [
    'metodo'    => 'lote',
    'usuario'   => 'SEU_USUARIO',
    'senha'     => 'SUA_SENHA',
    'celulares' => '5551999999999;5551888888888;5551777777777',
    'mensagens' => 'Olá João!;Olá Maria!;Olá Pedro!'
];

$options = [
    'http' => [
        'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
        'method'  => 'POST',
        'content' => http_build_query($data)
    ]
];

$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
echo $response;
// Sucesso: "OK 789012"
?>
Códigos de Resposta
Código Descrição
OK Lote enviado com sucesso
ERROR 01 Usuário ou senha inválidos
ERROR 02 Créditos insuficientes
ERROR 07 Quantidade de celulares e mensagens não corresponde
ERROR 08 Lista de celulares vazia
ERROR 99 Erro interno do servidor

Consulta de Status

GET /webservices/http.php?metodo=consulta Consultar status de entrega

Consulta o status de entrega de um SMS enviado.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
metodo string Sim Valor fixo: consulta
usuario string Sim Usuário da conta
senha string Sim Senha da conta
codigosms string Sim Código alfanumérico para uso interno do cliente (ex: 123456X3).

Exemplos

https://api.iagentesms.com.br/webservices/http.php?metodo=consulta&usuario=SEU_USUARIO&senha=SUA_SENHA&codigosms=123456
curl "https://api.iagentesms.com.br/webservices/http.php?metodo=consulta&usuario=SEU_USUARIO&senha=SUA_SENHA&codigosms=123456"
<?php
$params = [
    'metodo'    => 'consulta',
    'usuario'   => 'SEU_USUARIO',
    'senha'     => 'SUA_SENHA',
    'codigosms' => '123456'
];

$url = 'https://api.iagentesms.com.br/webservices/http.php?' . http_build_query($params);

$response = file_get_contents($url);
echo $response;
// Sucesso: "ENTREGUE"
?>
Códigos de Resposta
Código Descrição
ENVIADO Mensagem enviada para a operadora
ENTREGUE Mensagem entregue ao destinatário
FILA Mensagem na fila de envio
ERRO Falha no envio da mensagem
CANCELADO Envio cancelado
ERROR 01 Usuário ou senha inválidos
ERROR 09 ID de mensagem inválido
ERROR 99 Erro interno do servidor

API SOAP

A API SOAP oferece funcionalidades adicionais como gerenciamento de grupos, contatos e métodos de envio avançados.

WSDL e Autenticação

https://api.iagentesms.com.br/webservices/soap.php?wsdl

Todas as chamadas SOAP requerem os parâmetros usuario e senha como os dois primeiros argumentos de cada método.

Métodos de Grupos

SOAP criarGrupo Criar grupo de contatos

Cria um novo grupo de contatos.

Parâmetro Tipo Descrição
usuario string Usuário da conta
senha string Senha da conta
nome string Nome do grupo
SOAP listarGrupos Listar todos os grupos

Lista todos os grupos da conta.

Parâmetro Tipo Descrição
usuario string Usuário da conta
senha string Senha da conta
SOAP editarGrupo Editar nome de grupo

Edita o nome de um grupo existente.

Parâmetro Tipo Descrição
usuario string Usuário da conta
senha string Senha da conta
id_grupo int ID do grupo
nome string Novo nome do grupo
SOAP excluirGrupo Remover grupo

Remove um grupo e desvincula seus contatos.

Parâmetro Tipo Descrição
usuario string Usuário da conta
senha string Senha da conta
id_grupo int ID do grupo

Exemplo PHP - Grupos

<?php
$wsdl = 'https://api.iagentesms.com.br/webservices/soap.php?wsdl';
$client = new SoapClient($wsdl);

// Criar grupo
$resultado = $client->criarGrupo(
    'SEU_USUARIO',
    'SUA_SENHA',
    'Clientes VIP'
);
echo $resultado;

// Listar grupos
$resultado = $client->listarGrupos(
    'SEU_USUARIO',
    'SUA_SENHA'
);
print_r($resultado);
?>

Métodos de Contatos

SOAP criarContato Adicionar contato a grupo

Adiciona um contato a um grupo.

Parâmetro Tipo Descrição
usuario string Usuário da conta
senha string Senha da conta
id_grupo int ID do grupo
nome string Nome do contato
celular string Número com DDD
SOAP listarContatos Listar contatos de grupo

Lista contatos de um grupo.

Parâmetro Tipo Descrição
usuario string Usuário da conta
senha string Senha da conta
id_grupo int ID do grupo
SOAP editarContato Editar dados de contato

Edita os dados de um contato.

Parâmetro Tipo Descrição
usuario string Usuário da conta
senha string Senha da conta
id_contato int ID do contato
nome string Novo nome
celular string Novo número
SOAP excluirContato Remover contato

Remove um contato.

Parâmetro Tipo Descrição
usuario string Usuário da conta
senha string Senha da conta
id_contato int ID do contato

Exemplo PHP - Contatos

<?php
$wsdl = 'https://api.iagentesms.com.br/webservices/soap.php?wsdl';
$client = new SoapClient($wsdl);

// Adicionar contato ao grupo
$resultado = $client->criarContato(
    'SEU_USUARIO',
    'SUA_SENHA',
    42, // id_grupo
    'João Silva',
    '5551999999999'
);
echo $resultado;
?>

Envio Individual (SOAP)

SOAP enviarSMS Enviar SMS individual via SOAP

Envia SMS individual via SOAP.

Parâmetro Tipo Descrição
usuario string Usuário da conta
senha string Senha da conta
celular string Número do celular com DDD
mensagem string Texto da mensagem (máx. 160 caracteres por SMS)
agendamento string Data/hora opcional (DD/MM/AAAA HH:MM)
codigosms string Código alfanumérico para uso interno do cliente (ex: 123456X3), utilizado no envio de CALLBACK.

Exemplo

<?php
$wsdl = 'https://api.iagentesms.com.br/webservices/soap.php?wsdl';
$client = new SoapClient($wsdl);

// Envio individual
$resultado = $client->enviarSMS(
    'SEU_USUARIO',
    'SUA_SENHA',
    '5551999999999',
    'Olá! SMS via SOAP.',
    '' // agendamento (vazio = imediato)
);
echo $resultado;
?>

Envio em Lote (SOAP)

SOAP enviarSMSLote Enviar SMS em lote via SOAP

Envia SMS em lote via SOAP.

Parâmetro Tipo Descrição
usuario string Usuário da conta
senha string Senha da conta
celulares string Números separados por ;
mensagens string Mensagens separadas por ;
agendamento string Data/hora opcional (DD/MM/AAAA HH:MM)

Exemplo

<?php
$wsdl = 'https://api.iagentesms.com.br/webservices/soap.php?wsdl';
$client = new SoapClient($wsdl);

// Envio em lote
$resultado = $client->enviarSMSLote(
    'SEU_USUARIO',
    'SUA_SENHA',
    '5551999999999;5551888888888',
    'Msg para João;Msg para Maria',
    ''
);
echo $resultado;
?>

Envio para Grupo (SOAP)

SOAP enviarSMSGrupo Enviar SMS para grupo

Envia SMS para todos os contatos de um grupo.

Parâmetro Tipo Descrição
usuario string Usuário da conta
senha string Senha da conta
id_grupo int ID do grupo
mensagem string Texto da mensagem (máx. 160 caracteres por SMS)
agendamento string Data/hora opcional (DD/MM/AAAA HH:MM)

Exemplo

<?php
$wsdl = 'https://api.iagentesms.com.br/webservices/soap.php?wsdl';
$client = new SoapClient($wsdl);

// Envio para grupo
$resultado = $client->enviarSMSGrupo(
    'SEU_USUARIO',
    'SUA_SENHA',
    42, // id_grupo
    'Mensagem para todo o grupo!',
    ''
);
echo $resultado;
?>

Consulta de Status (SOAP)

SOAP consultarStatus Consultar status de entrega via SOAP

Consulta status de entrega via SOAP.

Parâmetro Tipo Descrição
usuario string Usuário da conta
senha string Senha da conta
codigosms string Código alfanumérico para uso interno do cliente (ex: 123456X3).

Exemplo

<?php
$wsdl = 'https://api.iagentesms.com.br/webservices/soap.php?wsdl';
$client = new SoapClient($wsdl);

// Consultar status
$resultado = $client->consultarStatus(
    'SEU_USUARIO',
    'SUA_SENHA',
    '123456' // id da mensagem
);
echo $resultado;
?>

Callback HTTP

O IAGENTEsms pode enviar notificações de status de entrega para uma URL configurada no seu painel. Quando o status de um SMS muda, o sistema faz uma requisição GET para a URL configurada com os seguintes parâmetros.

IMPORTANTE:

  • * O CALLBACK só funciona para mensagens invocadas via WebService com codigosms informado.
  • * O CALLBACK realiza até 10 (dez) tentativas de atualizações de STATUS aguardando retorno HTTP 200.

Parâmetros do Callback

Parâmetro Tipo Descrição
codigosms string Código alfanumérico para uso interno do cliente (ex: 123456X3).
celular string Número do destinatário
status string Status da entrega: ENTREGUE, ERRO, CANCELADO
data string Data/hora da atualização (DD/MM/AAAA HH:MM:SS)
operadora string Nome da operadora

Exemplo de Callback

GET https://seusite.com.br/callback/sms?codigosms=123456&celular=5551999999999&status=ENTREGUE&data=26/03/2026+14:32:10&operadora=VIVO

Recebendo Callback

<?php
// callback.php - Configure esta URL no painel do IAGENTEsms

$codigosms = $_GET['codigosms'] ?? '';
$celular   = $_GET['celular'] ?? '';
$status    = $_GET['status'] ?? '';
$data      = $_GET['data'] ?? '';
$operadora = $_GET['operadora'] ?? '';

// Registre o callback no seu banco de dados
$pdo = new PDO('mysql:host=localhost;dbname=seudb', 'usuario', 'senha');
$stmt = $pdo->prepare(
    "INSERT INTO sms_callbacks (msg_id, celular, status, data_status, operadora)
     VALUES (?, ?, ?, ?, ?)"
);
$stmt->execute([$codigosms, $celular, $status, $data, $operadora]);

// Retorne 200 OK para confirmar o recebimento
http_response_code(200);
echo 'OK';
?>

E-mail para SMS (SMTP)

O IAGENTEsms também permite o envio de SMS por e-mail. Basta enviar um e-mail para o endereço especial, e o conteúdo será convertido em SMS.

Formato do Endereço

NUMERO@sms.iagentesms.com.br

Onde NUMERO é o celular do destinatário com DDD (ex: 5551999999999@sms.iagentesms.com.br).

Configuração

Campo Valor
Para NUMERO@sms.iagentesms.com.br
De E-mail cadastrado no painel do IAGENTEsms
Assunto Será ignorado
Corpo Texto da mensagem SMS (máx. 160 caracteres)

O e-mail remetente deve estar previamente cadastrado e autorizado no painel para que o envio por SMTP funcione.

Precisa de ajuda? Entre em contato com nosso suporte técnico pelo WhatsApp ou acesse a Central de Ajuda.