Cadastro

Módulo Message

Criação, envio e outras funções para trabalhar com mensagens individuais (não envios em massa).

Métodos de API

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

Obter relatório de status de entrega de mensagem SMS

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âmetros da requisição

ParâmetroTipoDescrição
idsarray stringIdentificador(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.

Resposta do servidor

CampoTipoDescrição
idintegerIdentificador da mensagem.
statusstringStatus da mensagem.
Consulte a tabela Lista de status de mensagens possíveis.
segNumintegerNúmero de segmentos nesta mensagem.
startSendTsstringHora 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.
statusUpdateTsstringHora 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ódigos de resposta da API

CódigoDescrição
0Relatório de status de entrega obtido com sucesso.
2Se nenhum identificador de mensagem for especificado.
12Se mais de 100 identificadores de mensagem forem especificados.

Examples

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;
}

Obter lista de mensagens SMS

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âmetros da requisição

ParâmetroTipoDescrição
criteriaarrayCritérios de busca (consulte a tabela Critérios de busca).
paginationarrayParâmetros de paginação (consulte a tabela Parâmetros de paginação).
sortarrayParâmetros de ordenação (consulte a tabela Parâmetros de ordenação).
withNumberInfointegerEste 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.

Critérios de busca

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âmetroTipoDescrição
criteria[campaignIds]array \ stringBusca 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]stringBusca pelo ID do remetente.
A busca é feita pelo ID do remetente que foi criado na campanha.
criteria[to]stringBusca 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]stringBusca pelo texto da mensagem da campanha.
Realizada de acordo com o princípio de correspondência exata do valor pesquisado.
criteria[status]integerBusca pelo status da mensagem.
criteria[groups]stringBusca 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]stringBusca pelo status da campanha da mensagem SMS.
criteria[campaignCreateTsFrom]stringBusca 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]stringBusca pela data e hora de criação das campanhas até a data e hora especificadas.
Formato: AAAA-MM-DD HH:MM:SS.
criteria[campaignSentTsFrom]stringBusca pela data e hora das campanhas enviadas, a partir da data e hora especificadas.
Formato: AAAA-MM-DD HH:MM:SS.
criteria[campaignSentTsTo]stringBusca pela data e hora das campanhas enviadas até a data e hora especificadas.
Formato: AAAA-MM-DD HH:MM:SS.
criteria[startSendTsFrom]stringBusca pela data e hora das mensagens enviadas, a partir da data e hora especificadas.
Formato: AAAA-MM-DD HH:MM:SS.
criteria[startSendTsTo]stringBusca pela data e hora das mensagens enviadas até a data e hora especificadas.
Formato: AAAA-MM-DD HH:MM:SS.
criteria[statusUpdateTsFrom]stringBusca 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]stringBusca pela data e hora das mensagens cujo status foi alterado até a data e hora especificadas.
Formato: AAAA-MM-DD HH:MM:SS.

Parâmetros de paginação

Estes parâmetros foram criados para a saída estruturada (parcial) da informação solicitada.

ParâmetroTipoDescrição
pagination[pageSize]integerNúmero de elementos exibidos por página (25, 50, 100).
pagination[currentPage]integerPágina atual
A numeração das páginas começa em 0.

Parâmetros de ordenação

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âmetroDescriçã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.

Resposta do servidor

Array de dados:

CampoTipoDescrição
itemsarrayLista de mensagens encontradas (consulte a tabela Lista de mensagens).
totalItemCountintegerNúmero total de elementos encontrados.
Lista de mensagens

Cada uma das mensagens contém os campos:

CampoTipoDescrição
idintegerIdentificador da mensagem.
campaignIdintegerIdentificador da campanha da mensagem.
segNumintegerNúmero de segmentos.
segUserBuyfloatCusto do segmento da mensagem para o usuário
Indicado na moeda do usuário.
fromstringID do remetente.
tostringNúmero do destinatário.
textstringTexto da mensagem.
statusstringStatus da mensagem (consulte a tabela Lista de status de mensagens possíveis).
groupsstringIdentificadores de grupos de contatos aos quais o número do destinatário pertencia no momento da criação da campanha.
uuidstringIdentificador interno da mensagem.
countryA2stringCódigo do país do destinatário no formato ISO-3166 alpha2.
operatorNamestringNome da operadora do destinatário.
startSendTsdateData e hora de envio da mensagem.
Formato: AAAA-MM-DD HH:MM:SS.
statusUpdateTsdateData e hora da última atualização do status da mensagem.
Formato: AAAA-MM-DD HH:MM:SS.

Examples

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;
}

Enviar uma única mensagem SMS

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âmetros da requisição

ParâmetroTipoDescrição
recipientstringO 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.
textstringO 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.
fromstringID 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”.
paramsarrayParâmetros adicionais (veja a tabela Parâmetros Adicionais).

Parâmetros Adicionais

ParâmetroTipoDescrição
params[name]stringNome da campanha.
params[deferredToTs]stringData 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]integerFlag 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]integerTempo 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).

Resposta do servidor

Em caso de envio bem-sucedido da mensagem, a resposta contém um array com os seguintes campos:

CampoTipoDescrição
campaignIdintegerID da campanha SMS criada.
messageIdintegerID da mensagem SMS criada.
statusintegerStatus do envio da campanha SMS.
1 – campanha aguardando moderação;
2 – campanha enviada sem moderação.

Códigos de resposta da API

CódigoDescrição
0Mensagem SMS enviada com sucesso.
1Se algum parâmetro for especificado incorretamente.

Examples

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&params%5Bvalidity%5D=1440'
var data = "recipient=12223334455&text=Mensagem+SMS+de+teste&from=SeuAlpha&params%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;
}