Criação, envio e outras funções para trabalhar com mensagens individuais (não envios em massa).
Obter relatório de status de entrega de mensagem SMS
https://api.mobizon.com.br/service/Message/GetSMSStatus
Obter lista de mensagens SMS
https://api.mobizon.com.br/service/Message/List
Enviar uma única mensagem SMS
https://api.mobizon.com.br/service/Message/SendSmsMessage
https://api.mobizon.com.br/service/Message/GetSMSStatus
Este método permite obter dados sobre o status atual de entrega de uma ou mais mensagens SMS.
Independentemente do tipo de parâmetro de entrada, o resultado retornado é sempre apresentado na forma de um array.
Se forem passados identificadores de mensagens inexistentes ou que não pertencem ao usuário, o resultado não conterá informações sobre essas mensagens.
| Parâmetro | Tipo | Descrição |
|---|---|---|
ids | array string | Identificador(es) da(s) mensagem(ns). Array ou string de identificadores separados por vírgulas. O número máximo de identificadores em uma única requisição é 100. |
| Campo | Tipo | Descrição |
|---|---|---|
id | integer | Identificador da mensagem. |
status | string | Status da mensagem. Consulte a tabela Lista de status de mensagens possíveis. |
segNum | integer | Número de segmentos nesta mensagem. |
startSendTs | string | Hora de início do envio da mensagem. Formato: AAAA-MM-DD HH-MM-SS.Se a mensagem ainda não tiver sido enviada, o valor do campo será NULL. |
statusUpdateTs | string | Hora da última atualização do status da mensagem. Formato: AAAA-MM-DD HH-MM-SS.Se a mensagem ainda não tiver sido enviada, o valor do campo será NULL. |
| Código | Descrição |
|---|---|
| 0 | Relatório de status de entrega obtido com sucesso. |
| 2 | Se nenhum identificador de mensagem for especificado. |
| 12 | Se mais de 100 identificadores de mensagem forem especificados. |
curl -X POST \
'https://api.mobizon.com.br/service/message/getSMSStatus?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'ids%5B0%5D=123&ids%5B1%5D=556&ids%5B2%5D=988'
var data = "ids%5B0%5D=123&ids%5B1%5D=556&ids%5B2%5D=988";
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://api.mobizon.com.br/service/message/getSMSStatus?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK");
xhr.setRequestHeader("content-type", "application/x-www-form-urlencoded");
xhr.setRequestHeader("cache-control", "no-cache");
xhr.send(data);
<?php
use Mobizon\MobizonApi;
$api = new MobizonApi('KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK', 'api.mobizon.com.br');
// Chamada do método API
if ($api->call(
'message',
'getSMSStatus',
array(
//identificadores das mensagens
'ids' => array(
'123',
'556',
'988'
)
)
)
) {
// Obtenção do resultado da execução do método
$result = $api->getData();
} else {
// Ocorreu um erro durante a execução, exibição do código de erro e do texto da mensagem
echo '[' . $api->getCode() . '] ' . $api->getMessage() . PHP_EOL;
}
https://api.mobizon.com.br/service/Message/List
Este método permite obter uma lista das mensagens SMS criadas.
A busca pode ser realizada por ID e dados dos campos da campanha.
| Parâmetro | Tipo | Descrição |
|---|---|---|
criteria | array | Critérios de busca (consulte a tabela Critérios de busca). |
pagination | array | Parâmetros de paginação (consulte a tabela Parâmetros de paginação). |
sort | array | Parâmetros de ordenação (consulte a tabela Parâmetros de ordenação). |
withNumberInfo | integer | Este parâmetro permite obter informações adicionais do servidor sobre o número do destinatário, como "país" e "operadora". Valores possíveis: 0 – não receber (definido por padrão); 1 – receber. |
Informações sobre os campos da mensagem SMS pelos quais a busca é realizada. Para a busca, pode-se usar um único campo ou vários simultaneamente.
| Parâmetro | Tipo | Descrição |
|---|---|---|
criteria[campaignIds] | array \ string | Busca por identificadores de campanhas. O parâmetro deve ser passado como um array ou uma string de identificadores separados por vírgulas. O número máximo de identificadores é 100; se este limite for excedido, a busca ocorrerá pelos primeiros 100 IDs da lista. |
criteria[from] | string | Busca pelo ID do remetente. A busca é feita pelo ID do remetente que foi criado na campanha. |
criteria[to] | string | Busca pelo número de telefone do destinatário. A busca pode ser feita pelo número completo ou parte dele. Exemplo: 12223334455 – encontrará todas as campanhas em que este número participou;38097 – serão encontradas todas as campanhas com números contendo a combinação de dígitos especificada.Apenas um número pode participar da busca. |
criteria[text] | string | Busca pelo texto da mensagem da campanha. Realizada de acordo com o princípio de correspondência exata do valor pesquisado. |
criteria[status] | integer | Busca pelo status da mensagem. |
criteria[groups] | string | Busca pelos identificadores de grupos de contatos usados na campanha. O parâmetro deve ser passado como um array ou uma string de identificadores separados por vírgulas. |
criteria[campaignStatus] | string | Busca pelo status da campanha da mensagem SMS. |
criteria[campaignCreateTsFrom] | string | Busca pela data e hora de criação das campanhas, a partir da data e hora especificadas. Formato: AAAA-MM-DD HH:MM:SS. |
criteria[campaignCreateTsTo] | string | Busca pela data e hora de criação das campanhas até a data e hora especificadas. Formato: AAAA-MM-DD HH:MM:SS. |
criteria[campaignSentTsFrom] | string | Busca pela data e hora das campanhas enviadas, a partir da data e hora especificadas. Formato: AAAA-MM-DD HH:MM:SS. |
criteria[campaignSentTsTo] | string | Busca pela data e hora das campanhas enviadas até a data e hora especificadas. Formato: AAAA-MM-DD HH:MM:SS. |
criteria[startSendTsFrom] | string | Busca pela data e hora das mensagens enviadas, a partir da data e hora especificadas. Formato: AAAA-MM-DD HH:MM:SS. |
criteria[startSendTsTo] | string | Busca pela data e hora das mensagens enviadas até a data e hora especificadas. Formato: AAAA-MM-DD HH:MM:SS. |
criteria[statusUpdateTsFrom] | string | Busca pela data e hora das mensagens cujo status foi alterado, a partir da data e hora especificadas. Formato: AAAA-MM-DD HH:MM:SS. |
criteria[statusUpdateTsTo] | string | Busca pela data e hora das mensagens cujo status foi alterado até a data e hora especificadas. Formato: AAAA-MM-DD HH:MM:SS. |
Estes parâmetros foram criados para a saída estruturada (parcial) da informação solicitada.
| Parâmetro | Tipo | Descrição |
|---|---|---|
pagination[pageSize] | integer | Número de elementos exibidos por página (25, 50, 100). |
pagination[currentPage] | integer | Página atual A numeração das páginas começa em 0. |
Com esses parâmetros, você pode ordenar os resultados da busca por um dos campos em ordem crescente (ASC) ou decrescente (DESC).
Exemplo:
Ordenação pelo número do destinatário em ordem crescente – sort[to]: ASC.
Ordenação pelo status da mensagem em ordem decrescente – sort[status]: DESC.
| Parâmetro | Descrição |
|---|---|
sort[campaignId] | Ordenação pelo identificador da campanha. |
sort[from] | Ordenação pelo ID do remetente. |
sort[to] | Ordenação pelo número do destinatário. |
sort[text] | Ordenação pelo texto. |
sort[status] | Ordenação pelo status da mensagem. |
sort[startSendTs] | Ordenação pela hora de envio. |
sort[statusUpdateTs] | Ordenação pela atualização do status. |
sort[segNum] | Ordenação pelo número de segmentos. |
Array de dados:
| Campo | Tipo | Descrição |
|---|---|---|
items | array | Lista de mensagens encontradas (consulte a tabela Lista de mensagens). |
totalItemCount | integer | Número total de elementos encontrados. |
Cada uma das mensagens contém os campos:
| Campo | Tipo | Descrição |
|---|---|---|
id | integer | Identificador da mensagem. |
campaignId | integer | Identificador da campanha da mensagem. |
segNum | integer | Número de segmentos. |
segUserBuy | float | Custo do segmento da mensagem para o usuário Indicado na moeda do usuário. |
from | string | ID do remetente. |
to | string | Número do destinatário. |
text | string | Texto da mensagem. |
status | string | Status da mensagem (consulte a tabela Lista de status de mensagens possíveis). |
groups | string | Identificadores de grupos de contatos aos quais o número do destinatário pertencia no momento da criação da campanha. |
uuid | string | Identificador interno da mensagem. |
countryA2 | string | Código do país do destinatário no formato ISO-3166 alpha2. |
operatorName | string | Nome da operadora do destinatário. |
startSendTs | date | Data e hora de envio da mensagem. Formato: AAAA-MM-DD HH:MM:SS. |
statusUpdateTs | date | Data e hora da última atualização do status da mensagem. Formato: AAAA-MM-DD HH:MM:SS. |
curl -X POST \
'https://api.mobizon.com.br/service/message/list?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'criteria%5Bfrom%5D=Alpha&pagination%5BcurrentPage%5D=2&pagination%5BpageSize%5D=50&sort%5BcampaignId%5D=ASC'
var data = "criteria%5Bfrom%5D=Alpha&pagination%5BcurrentPage%5D=2&pagination%5BpageSize%5D=50&sort%5BcampaignId%5D=ASC";
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://api.mobizon.com.br/service/message/list?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK");
xhr.setRequestHeader("content-type", "application/x-www-form-urlencoded");
xhr.setRequestHeader("cache-control", "no-cache");
xhr.send(data);
<?php
use Mobizon\MobizonApi;
$api = new MobizonApi('KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK', 'api.mobizon.com.br');
// Chamada do método API
if ($api->call(
'message',
'list',
array(
//critérios de busca
'criteria' => array(
//assinatura do remetente
'from' => 'Alpha'
),
//parâmetros de paginação
'pagination' => array(
//página atual
'currentPage' => '2',
//número de elementos exibidos por página
'pageSize' => '50'
),
//parâmetros de ordenação
'sort' => array(
//ordenação por identificador da campanha
'campaignId' => 'ASC'
)
)
)
) {
// Obtenção do resultado da execução do método
$result = $api->getData();
} else {
// Ocorreu um erro durante a execução, exibição do código de erro e do texto da mensagem
echo '[' . $api->getCode() . '] ' . $api->getMessage() . PHP_EOL;
}
https://api.mobizon.com.br/service/Message/SendSmsMessage
Este método permite que você envie uma única mensagem SMS para um número de telefone celular especificado.
| Parâmetro | Tipo | Descrição |
|---|---|---|
recipient | string | O número de telefone do destinatário para a mensagem SMS. O número deve estar no formato internacional e conter apenas dígitos. Por exemplo: 12223334455. Se o número tiver um “+” no início, ele deve ser codificado como %2B ou removido, deixando apenas dígitos. |
text | string | O texto da mensagem SMS, codificado em codificação URL. Se o sistema não retornar uma resposta com os dados da mensagem ao tentar enviar uma mensagem usando uma requisição GET, primeiro verifique se há caracteres especiais no corpo da requisição, tais como: ? / \ & + e [espaço].A presença de tais caracteres indica que o texto não foi codificado. |
from | string | ID do remetente. Para usar seu próprio ID de remetente, ele deve primeiro ser registrado. Se o ID do remetente não for especificado, será usado o ID de remetente padrão selecionado em sua conta. Se você não tiver IDs de remetente registrados ou se não for possível enviar com o ID de remetente especificado, um dos IDs de remetente compartilhados do serviço será usado, se possível. Para mais detalhes sobre IDs de remetente, consulte a seção “IDs de remetente”. |
params | array | Parâmetros adicionais (veja a tabela Parâmetros Adicionais). |
| Parâmetro | Tipo | Descrição |
|---|---|---|
params[name] | string | Nome da campanha. |
params[deferredToTs] | string | Data e hora do envio diferido da mensagem SMS. Você pode definir o início do envio para não antes de uma hora e não depois de 14 dias. Formato: AAAA-MM-DD HH:MM:SS. |
params[shortenLinks] | integer | Flag indicando a necessidade de aplicar a função de encurtamento de links a todos os links no texto do SMS. Padrão: 0 (desativado). Defina como 1 para ativar. |
params[validity] | integer | Tempo máximo de espera para a entrega da mensagem se o destinatário não puder recebê-la imediatamente. Por exemplo, se o telefone do destinatário estiver desligado ou fora da área de cobertura. Especificado em minutos a partir do momento do envio: de 60 minutos (1 hora) a 1440 minutos (24 horas). |
Em caso de envio bem-sucedido da mensagem, a resposta contém um array com os seguintes campos:
| Campo | Tipo | Descrição |
|---|---|---|
| campaignId | integer | ID da campanha SMS criada. |
| messageId | integer | ID da mensagem SMS criada. |
| status | integer | Status do envio da campanha SMS. 1 – campanha aguardando moderação; 2 – campanha enviada sem moderação. |
| Código | Descrição |
|---|---|
| 0 | Mensagem SMS enviada com sucesso. |
| 1 | Se algum parâmetro for especificado incorretamente. |
curl -X POST \
'https://api.mobizon.com.br/service/message/sendSmsMessage?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'recipient=12223334455&text=Mensagem+SMS+de+teste&from=SeuAlpha¶ms%5Bvalidity%5D=1440'
var data = "recipient=12223334455&text=Mensagem+SMS+de+teste&from=SeuAlpha¶ms%5Bvalidity%5D=1440";
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://api.mobizon.com.br/service/message/sendSmsMessage?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK");
xhr.setRequestHeader("content-type", "application/x-www-form-urlencoded");
xhr.setRequestHeader("cache-control", "no-cache");
xhr.send(data);
<?php
use 'Mobizon\MobizonApi.php';
$api = new Mobizon\MobizonApi('KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK', 'api.mobizon.com.br');
// Chamada de API para enviar uma mensagem
if ($api->call('message',
'sendSMSMessage',
array(
// Número de telefone internacional do destinatário
'recipient' => '12223334455',
// Texto da mensagem
'text' => 'Mensagem SMS de teste',
// Alphaname é opcional; se você não tiver um alphaname registrado, apenas ignore este parâmetro e sua mensagem será enviada com nosso alphaname comum gratuito, se disponível para esta direção.
'from' => 'SeuAlpha',
// A mensagem expirará após 1440 min (24h)
'params[validity]' => 1440
))
) {
// Obtenha o ID da mensagem atribuído pelo nosso sistema para solicitar seu relatório de entrega mais tarde.
$messageId = $api->getData('messageId');
if (!$messageId) {
// A mensagem não foi aceita, veja o código de erro e os dados para detalhes.
}
// A mensagem foi aceita pela API.
} else {
// Ocorreu um erro ao enviar a mensagem
echo '[' . $api->getCode() . '] ' . $api->getMessage() . ' Veja os detalhes abaixo:' . PHP_EOL . print_r($api->getData(), true) . PHP_EOL;
}