Cadastro

Módulo Campaign

Este módulo contém funções para criar campanhas de SMS, adicionar destinatários de uma das formas possíveis, iniciar o envio da campanha, excluir campanhas irrelevantes, visualizar a lista de campanhas e realizar buscas nelas.

Métodos de API

Adicionar destinatários a uma campanha de SMS em massa
https://api.mobizon.com.br/service/Campaign/AddRecipients

Criação de uma nova campanha
https://api.mobizon.com.br/service/Campaign/Create

Excluir campanha
https://api.mobizon.com.br/service/Campaign/Delete

Obter dados básicos da campanha
https://api.mobizon.com.br/service/Campaign/Get

Obter dados estatísticos da campanha
https://api.mobizon.com.br/service/Campaign/GetInfo

Obter lista de campanhas
https://api.mobizon.com.br/service/Campaign/List

Enviar campanha
https://api.mobizon.com.br/service/Campaign/Send

Adicionar destinatários a uma campanha de SMS em massa

https://api.mobizon.com.br/service/Campaign/AddRecipients

Em uma única requisição, é permitida apenas a transferência de dados sobre destinatários de um único tipo:

  • lista de números/IDs de cartões de contato/IDs de contatos
  • lista de IDs de grupos da agenda de contatos
  • arquivo com a lista de destinatários.

Ao tentar transferir vários tipos diferentes de destinatários de uma só vez, o erro 12 será retornado. Se for necessário adicionar destinatários de várias fontes a uma única campanha, isso deve ser feito em várias requisições.

Ao adicionar números de destinatários, contatos ou cartões de contato, o número máximo de destinatários carregados em uma única requisição não pode exceder 500 números. Se o limite for excedido, o erro 12 será retornado e os destinatários não serão adicionados.

Para carregar qualquer quantidade desejada de contatos em uma única campanha, você deve dividir a lista em porções de 500 ou menos e carregar cada porção com uma chamada de API separada - os destinatários serão adicionados à lista já existente, a menos que o parâmetro replace=1 seja especificado.

O carregamento de números, contatos e cartões é realizado na thread principal do servidor web e retorna o resultado para cada destinatário processado na forma de um array (veja o formato dos dados retornados abaixo).

O carregamento de um grupo de contatos ou de um arquivo aciona a criação de uma tarefa em segundo plano (carregamento assíncrono) e retorna seu ID para acompanhamento posterior do status. Neste caso, o código de resposta da API será 100.

Os números dos destinatários devem ser passados no formato internacional. Todos os caracteres estranhos serão removidos do número automaticamente.

Cada número é verificado quanto à possibilidade de enviar uma mensagem para ele de acordo com o código do país e da operadora a que pertence.

Todos os números que não passarem na verificação serão rejeitados com o código de erro correspondente (code), e para cada número adicionado será retornado o ID da mensagem criada (messageId) para a possibilidade de solicitação de status posterior.

Se nem todos os destinatários passados foram adicionados (ocorreram erros), a API pode retornar um dos dois códigos de resposta:

  • 98 - se nem todos os destinatários foram adicionados, mas pelo menos um destinatário passou na verificação
  • 99 - se nenhum destinatário passou na verificação.

Durante todo o tempo de adição de destinatários, a campanha é bloqueada para adição por outros processos, portanto, a adição paralela em várias threads a uma única campanha é impossível.

Parâmetros da requisição

ParâmetroTipoDescrição
idintegerIdentificador da campanha na qual os destinatários devem ser adicionados.
recipientsarray stringPara um envio normal (sem o uso de variáveis placeholder no texto), os destinatários podem ser passados como:
  • string com os números dos destinatários, separados por vírgulas ou quebras de linha;
  • array unidimensional, onde cada elemento do array corresponde a um número de destinatário;
  • array bidimensional, onde cada elemento é um array contendo um elemento com a chave recipient e o número do destinatário como valor.
Para um envio de modelo, os destinatários devem ser passados como um array bidimensional, onde cada elemento é um array contendo um elemento com a chave recipient e o número do destinatário como valor. Além disso, neste array podem estar elementos com chaves correspondentes aos nomes das variáveis (placeholders) no texto do SMS (sem as chaves envolventes).
Neste caso, se algum dos placeholders contidos no texto não for passado no array de dados, o processamento ocorrerá dependendo do valor passado no parâmetro params[placeholdersFlag] (veja a descrição deste parâmetro abaixo).
recipientContactsarray stringArray ou string de contatos da agenda de contatos separados por vírgulas ou quebras de linha. Um contato pode ser especificado como:
  • identificador do cartão. Neste caso, o valor do campo 'número de telefone celular' marcado como campo para envio de correspondências será usado para o envio;
  • {identificador do cartão}:{chave do campo do cartão} (por exemplo: 123456:mobile, se o campo de telefone celular em sua agenda tiver a chave 'mobile'). O valor do campo do cartão especificado será usado para o envio.
Se o envio for de modelo, os dados para preencher os placeholders no texto serão usados do cartão de contato correspondente.
recipientGroupsarray stringArray ou string de identificadores de grupos da agenda de contatos, separados por vírgulas ou quebras de linha, a partir dos quais a campanha será formada. Se o mesmo contato estiver contido em vários grupos, ele será adicionado à campanha apenas uma vez. Se vários contatos contiverem o mesmo número de telefone, apenas o primeiro deles será adicionado.
recipientsFilefileObjeto do arquivo carregado com destinatários - arquivo CSV ou Excel (apenas XLS) com números de destinatários no formato internacional.
Para envio normal (sem o uso de variáveis placeholder no texto) - números um por linha.
Para envio de modelo - números um por linha em uma das colunas com o cabeçalho recipient, nas outras colunas podem estar dados para substituição nos placeholders. Os cabeçalhos de tais colunas (na primeira linha da tabela) devem corresponder estritamente aos placeholders no texto do SMS (sem as chaves envolventes, respeitando a diferenciação entre maiúsculas e minúsculas). Para nomes de placeholders, apenas letras latinas e números, bem como os símbolos '_','-' são permitidos. Se houver colunas com cabeçalhos idênticos, um erro será retornado.
Neste caso, se não houver colunas correspondentes para algum dos placeholders contidos no texto, o processamento ocorrerá dependendo do valor passado no parâmetro params[placeholdersFlag] (veja a descrição deste parâmetro abaixo).
paramsarrayConfigurações adicionais (veja a tabela Configurações Adicionais).
Configurações Adicionais
ParâmetroTipoDescrição
params[replace]integerIndica se todos os destinatários já adicionados devem ser removidos e a adição deve ser iniciada novamente:
0 - não, adicionar destinatários aos já adicionados anteriormente (valor padrão);
1 - sim, remover todos os destinatários adicionados anteriormente antes de adicionar novos;
params[placeholdersFlag]integerProcessamento de variáveis (placeholders) ausentes para envio de modelo.
Se nenhum valor de variável para substituição no texto for encontrado, um dos seguintes comportamentos é possível:
1 - a mensagem é adicionada ao envio, mas os placeholders permanecem no texto como estão, a substituição não ocorre (comportamento padrão);
2 - a mensagem é adicionada e os placeholders são removidos (pode ser útil se você usa chaves no texto e não quer que elas sejam removidas no envio);
3 - a mensagem é rejeitada com um erro informando sobre os dados ausentes para substituição no texto.
params[recipientsFileEncoding]stringCodificação do arquivo com os dados dos destinatários. Codificações disponíveis: KOI8-R, CP866, WINDOWS-1252, WINDOWS-1251, UTF-8, ASCII, ISO-8859-1, UCS-2. Padrão: UTF-8.
params[recipientsFileSkipHeader]integerIndica se a primeira linha do arquivo deve ser ignorada e o processamento deve ser iniciado a partir da segunda. Útil se o carregamento de destinatários for feito a partir de um arquivo que contém os nomes das colunas na primeira linha. Neste caso, é melhor ignorar a primeira linha e começar a processar o arquivo a partir da segunda linha. Valores possíveis:
0 - começar pela primeira linha (valor padrão);
1 - ignorar a primeira linha do arquivo e começar o processamento a partir da segunda (definido obrigatoriamente no caso de envio de modelo);
No caso de envio de modelo, o valor deste parâmetro é sempre 1 e não pode ser substituído, pois a primeira linha deve conter os nomes das variáveis para substituição.
params[recipientsFileDelimiter]stringSeparador de colunas no arquivo com os dados dos destinatários, padrão: , (vírgula). Se necessário, você pode usar qualquer outro caractere.
params[recipientsFileEnclosure]stringDelimitador de texto no arquivo com os dados dos destinatários, padrão: ' (aspa simples). Este caractere deve envolver os textos nas colunas que contêm o caractere separador em ambos os lados, para que o sistema possa analisar o arquivo em colunas corretamente.

Resposta do servidor

array | integer : Ao carregar destinatários de uma lista de números, contatos ou cartões de contato, um array é retornado, cada elemento do qual contém dados sobre os destinatários carregados:

CampoTipoDescrição
recipientstringNúmero do destinatário que está sendo adicionado à campanha.
codeintegerCódigo do resultado da adição do destinatário:
0 - número adicionado com sucesso à campanha
1 - o número de telefone está ausente nos dados passados ou seu valor está vazio
2 - nenhum número de telefone foi detectado nos dados passados (provavelmente os dados estão formatados incorretamente)
3 - o número não corresponde ao formato internacional de números de telefone
4 - o número já foi adicionado à campanha (exclusão de duplicatas do envio)
5 - o número está na lista de bloqueio (pode ser a sua lista de bloqueio ou a lista de bloqueio do sistema)
6 - o envio para o país de destino é limitado pelas configurações da sua conta
7 - não é possível determinar a operadora e/ou o país de destino
8 - o sistema não tem a possibilidade de enviar para esta operadora, entre em contato com nosso suporte técnico para esclarecer a possibilidade de envio
20 - os dados passados não contêm todos os placeholders necessários (se placeholdersFlag estiver definido como 1)
30 - o cartão de contato não foi encontrado na agenda de contatos (recipient será igual a null)
31 - o cartão de contato não contém um número de celular (recipient será igual a null)
32 - o contato não foi encontrado na agenda de contatos (recipient será igual a null)
51 - por razões técnicas, não é possível criar um link curto no momento
99 - erro de sistema ao adicionar o número do destinatário
messageIdintegerIdentificador da mensagem adicionada, se o número foi adicionado, o status da mensagem pode ser obtido pelo identificador especificado.
numberintegerO valor original do número do destinatário passado pelo usuário (se o número do destinatário foi passado).
contactintegerIdentificador do contato passado (se recipientContacts foi passado).

Ao carregar um arquivo com destinatários ou uma lista de grupos de contatos, é retornado um identificador numérico da tarefa de adição de destinatários em segundo plano. Detalhes sobre o trabalho com tarefas em segundo plano veja aqui.

Códigos de erro

CódigoDescrição
1Se algum parâmetro contiver valores inválidos.
2Se a campanha com o ID especificado não for encontrada.
10Se a campanha especificada for bloqueada por outro processo de adição de destinatários ou se o status da campanha não permitir a adição de destinatários.
12Se nenhum tipo de destinatário for passado ou se vários tipos de destinatários forem passados em uma única requisição.
98Se, de todos os destinatários passados, pelo menos um não tiver sido adicionado à campanha.
99Se nenhum destinatário tiver sido adicionado à campanha como resultado da execução da requisição.
100Se uma tarefa de segundo plano para adicionar destinatários foi iniciada. Detalhes sobre o trabalho com tarefas em segundo plano veja aqui.

Exemplos

Adicionar números de destinatários a um envio em massa.

Para adicionar uma lista de destinatários ao envio, você pode passar o array deles assim:

recipients[]=380971112233&recipients[]=79101112233&recipients[]=77071112233

ou assim:

recipients=380971112233,79101112233,77071112233

Ambas as formas de registro são idênticas.

Adicionar dados para envio de modelo.

Suponhamos que o texto do SMS seja o seguinte: Olá, {name}! Seu saldo em {date} é de {balance}{currency}. Neste caso, no parâmetro recipients, os dados devem ser passados na seguinte forma:

recipients[0][recipient]=380971112233
&recipients[0][name]=%D0%92%D0%B0%D1%81%D0%B8%D0%BB%D0%B8%D0%B9
&recipients[0][date]=26.10.17
&recipients[0][balance]=123.45
&recipients[0][currency]=%D0%B3%D1%80%D0%BD
&recipients[1][recipient]=380971112255
&recipients[1][name]=%D0%9E%D0%BB%D1%8C%D0%B3%D0%B0
&recipients[1][date]=26.10.17
&recipients[1][balance]=3222.99
&recipients[1][currency]=%D1%80%D1%83%D0%B1
&recipients[2][recipient]=4901122211112
&recipients[2][name]=Markus
&recipients[2][date]=26.10.17
&recipients[2][balance]=555.45
&recipients[2][currency]=eur

Todos os dados nos campos de requisição HTTP transmitidos para o servidor devem ser previamente codificados em string codificada em URL (cada linguagem de programação tem uma função correspondente para isso).

Criação de uma nova campanha

https://api.mobizon.com.br/service/Campaign/Create

Este método permite que você crie uma nova campanha SMS. Após criar a campanha, você deve adicionar destinatários e, em seguida, enviá-la.

Parâmetros da requisição

data array – Parâmetros da campanha

ParâmetroTipoDescrição
data[name]stringNome da campanha.
Este campo facilita a navegação pelas campanhas criadas.
Por exemplo: "Descontos da Black Friday" ou "Lembrete de Saldo Negativo".
O comprimento máximo do nome da campanha é de 255 caracteres.
data[text]stringTexto da mensagem SMS a ser enviada.
Para campanhas de modelo (data[type]=3), este texto deve conter variáveis que serão substituídas por valores únicos para cada destinatário. A variável deve ser escrita com letras latinas, números e os símbolos «_» ,«-», e envolta em chaves, por exemplo: {name} ou {clientBalance}.
Requisitos de texto de SMS.
No texto da mensagem, você pode usar links curtos e o recurso de rastreamento de destinatários para ver quem entre os destinatários clicou no seu link.
data[type]integerTipo de campanha:
1 – Mensagem única (enviada para um número);
2 – Envio em massa (definido por padrão);
3 – Campanha de modelo (o texto da mensagem pode conter espaços reservados que serão substituídos por texto único para cada destinatário).
data[from]stringID do remetente.
Para usar um ID de remetente personalizado, ele deve ser registrado antecipadamente.
Se o ID do remetente não for especificado, será usado o ID de remetente padrão ou padrão do serviço.
data[rateLimit]integerO limite do número de mensagens enviadas no período especificado no campo ratePeriod.
Esta opção permite que você reduza a velocidade de envio de um grande envio de SMS para distribuir a carga em seu Call Center.
O limite de velocidade de envio não é superior a 100 mensagens por segundo quando calculado por segundo.
As mensagens são enviadas em intervalos iguais em lotes de 10, com base no rateLimit especificado por ratePeriod. Por exemplo, se você especificar uma velocidade de 600 e um período de 60, 600/60=10 SMS serão enviados a cada segundo.
data[ratePeriod]integerO período em segundos durante o qual o número de SMS especificado no campo rateLimit será enviado.
Pode ser:
60 – 1 minuto;
3600 – 1 hora;
86400 – 1 dia.
data[deferredToTs]stringData e hora do envio diferido da campanha.
O início do envio pode ser definido para não antes de uma hora depois e não depois de 14 dias.
Formato: AAAA-MM-DD HH:MM:SS.
data[validity]integerO 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 estiver desligado ou fora da cobertura da rede.
Especificado em minutos a partir do momento do envio: de 60 (1 hora) a 1440 (24 horas).
data[shortenLinks]integerEncurtar links no texto - 1, padrão não encurtar - 0.
data[trackShortLinkRecipients]integerRecurso de rastreamento de destinatários.
Disponível para uso apenas se houver links curtos criados em nosso serviço no texto da mensagem (no campo data[text]).
0 – não usar o recurso (padrão);
1 – usar o recurso.

Resposta do servidor

integer – identificador da campanha, se for criada com sucesso.

Códigos de resposta da API

CódigoDescrição
0A campanha foi criada com sucesso.
1Se algum parâmetro contiver valores inválidos.

Examples

curl -X POST \
  'https://api.mobizon.com.br/service/campaign/create?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'data%5Btype%5D=3&data%5Bfrom%5D=Alpha&data%5Btext%5D=Ol%C3%A1%2C+%7Bname%7D%21+Seu+saldo+em+%7Bdate%7D+%C3%A9+de+%7Bbalance%7D%7Bcurrency%7D.'
var data = "data%5Btype%5D=3&data%5Bfrom%5D=Alpha&data%5Btext%5D=Ol%C3%A1%2C+%7Bname%7D%21+Seu+saldo+em+%7Bdate%7D+%C3%A9+de+%7Bbalance%7D%7Bcurrency%7D.";

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/campaign/create?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(
    'campaign',
    'create',
    array(
        //parâmetros da campanha
        'data' => array(
            //tipo de campanha
            'type' => '3',
            //assinatura do remetente
            'from' => 'Alpha',
            //texto da mensagem
            'text' => 'Olá, {name}! Seu saldo em {date} é de {balance}{currency}.'
        )
    )
)
) {
    // 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;
}

Excluir campanha

https://api.mobizon.com.br/service/Campaign/Delete

Este método permite excluir uma campanha por seu ID.
Uma campanha pode ser excluída se o seu envio ainda não tiver começado.
Se a campanha estiver agendada: uma campanha agendada pode ser excluída, desde que faltem pelo menos 5 minutos para o início do envio.

Parâmetros da requisição

ParâmetroTipoDescrição
idintegerIdentificador da campanha.

Códigos de resposta da API

CódigoDescrição
0Campanha excluída com sucesso.
2Se a campanha com o identificador especificado não for encontrada.
10Se a campanha com o identificador especificado não puder ser excluída.

Examples

curl -X POST \
  'https://api.mobizon.com.br/service/campaign/delete?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'id=123'
var data = "id=123";

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/campaign/delete?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(
    'campaign',
    'delete',
    array(
        //identificador da campanha
        'id' => '123'
    )
)
) {
    // 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 dados básicos da campanha

https://api.mobizon.com.br/service/Campaign/Get

Este método permite obter os dados básicos de uma campanha criada por seu ID.

Parâmetros da requisição

ParâmetroTipoDescrição
idintegerIdentificador da campanha.

Resposta do servidor

Um array de dados contendo os seguintes campos:

CampoTipoDescrição
idstringIdentificador da campanha.
moderationStatusstringStatus atual da moderação:
MODERATION – a campanha está em moderação;
DECLINED – a campanha foi recusada pelo moderador;
READY_FOR_SEND – a campanha foi autorizada pelo moderador;
AUTO_READY_FOR_SEND – a campanha foi enviada sem moderação.
commonStatusstringStatus atual da campanha:
MODERATION – a campanha está passando por moderação;
DECLINED – a campanha foi recusada pelo moderador (o motivo da recusa é indicado no campo globalComment);
READY_FOR_SEND – a campanha está pronta para envio, mas o envio ainda não começou;
RUNNING – a campanha está em processo de envio;
SENT – a campanha foi totalmente enviada, mas nem todas as mensagens receberam relatório de entrega da operadora;
DONE – a campanha foi totalmente concluída: todos os relatórios finais de entrega foram recebidos, os contadores contêm os valores finais.
groupsListarrayLista de grupos de contatos incluídos na campanha.
Para cada grupo contém:
id – número do grupo;
name – nome do grupo;
cardsCnt – número de contatos no grupo disponíveis para envio de mensagem.
Se nenhum grupo foi usado na campanha, este campo estará vazio.
typeintegerTipo de campanha:
1 – Mensagem única (enviada para um número);
2 – Envio em massa;
3 – Campanha de modelo;
7 – Campanha funcional (de serviço).
msgTypestringTipo de mensagens da campanha.
Atualmente, apenas o tipo "SMS" é suportado.
rateLimitintegerLimite do número de mensagens enviadas no período especificado no campo ratePeriod.
ratePeriodintegerPeríodo de tempo em segundos durante o qual o número de SMS especificado no campo rateLimit será enviado.
sendStatusstringStatus de envio da campanha:
SENT – a campanha foi enviada;
DONE – a campanha foi concluída.
isDeletedintegerFlag indicando que a campanha foi excluída:
0 – a campanha está disponível;
1 – a campanha foi excluída.
deferredToTsstringData e hora do envio agendado da campanha.
Formato: AAAA-MM-DD HH:MM:SS.
createTsstringData e hora de criação da campanha.
Formato: AAAA-MM-DD HH:MM:SS.
startSendTsstringData e hora do início real do envio da campanha.
Formato: AAAA-MM-DD HH:MM:SS.
endSendTsstringData e hora do término do envio de todas as mensagens da campanha.
Formato: AAAA-MM-DD HH:MM:SS.
namestringNome da campanha.
fromstringID do remetente que foi selecionado para o envio da campanha.
textstringTexto completo da mensagem ou texto de modelo com espaços reservados.
validityintegerTempo máximo de espera para entrega da mensagem, caso o destinatário não possa recebê-la imediatamente, em minutos a partir do momento do envio.
mclassintegerClasse da mensagem enviada:
0 – as mensagens são exibidas em uma janela pop-up e não são salvas em lugar nenhum (flashSMS);
1 – as mensagens são salvas na pasta de mensagens recebidas do telefone.
trackShortLinkRecipientsintegerSe a função de rastreamento de destinatários foi usada:
0 – a função não foi usada;
1 – a função foi usada.
groupsstringIdentificadores de grupos de contatos usados na campanha, separados por vírgulas.
globalCommentstringComentário do moderador, caso a campanha tenha sido recusada.

Examples

curl -X POST \
  'https://api.mobizon.com.br/service/campaign/get?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'id=123'
var data = "id=123";

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/campaign/get?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(
    'campaign',
    'get',
    array(
        //identificador da campanha
        'id' => '123'
    )
)
) {
    // 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 dados estatísticos da campanha

https://api.mobizon.com.br/service/Campaign/GetInfo

Este método permite obter os dados básicos e estatísticos da campanha por seu ID.

As estatísticas são formadas usando vários contadores, que são exibidos no campo counters.

IMPORTANTE!

Devido a características técnicas do cálculo do custo da campanha, os dados sobre o custo possível da campanha são indicados no momento da adição dos destinatários e não mudam com o tempo.

Alterações podem ocorrer apenas no caso de um novo carregamento de destinatários ou ao editar os dados da campanha (no caso de edição de dados, todos os destinatários e cálculos são resetados – um novo carregamento é necessário).

Parâmetros da requisição

ParâmetroTipoDescrição
idintegerIdentificador da campanha.
getFilledTplCampaignTextintegerFormato dos dados retornados:
0 – texto da campanha com espaços reservados;
1 – retornar o texto da campanha de modelo preenchido com os dados reais do destinatário (padrão).

Resposta do servidor

CampoTipoDescrição
idintegerIdentificador da campanha.
moderationStatusstringStatus atual da moderação:
MODERATION – a campanha está em moderação;
DECLINED – a campanha foi recusada pelo moderador;
READY_FOR_SEND – a campanha foi autorizada pelo moderador;
AUTO_READY_FOR_SEND – a campanha foi enviada sem moderação.
commonStatusstringStatus atual da campanha:
MODERATION – a campanha está passando por moderação;
DECLINED – a campanha foi recusada pelo moderador (o motivo da recusa é indicado no campo globalComment);
READY_FOR_SEND – a campanha está pronta para envio, mas o envio ainda não começou;
RUNNING – a campanha está em processo de envio;
SENT – a campanha foi totalmente enviada, mas nem todas as mensagens receberam relatório de entrega da operadora;
DONE – a campanha foi totalmente processada, todos os relatórios finais de entrega foram recebidos.
groupsListarrayLista de grupos de contatos incluídos na campanha.
Para cada grupo contém:
id – número do grupo;
name – nome do grupo;
cardsCnt – número de contatos no grupo disponíveis para envio de mensagem.
Se nenhum grupo foi usado na campanha, este campo estará vazio.
typeintegerTipo de campanha:
1 – Mensagem única (enviada para um número);
2 – Envio em massa;
3 – Campanha de modelo;
7 – Campanha funcional (de serviço).
msgTypestringTipo de mensagens da campanha.
Atualmente, apenas o tipo "SMS" é suportado.
rateLimitintegerLimite do número de mensagens enviadas no período especificado no campo ratePeriod.
ratePeriodintegerPeríodo durante o qual o número de SMS especificado no campo rateLimit será enviado.
sendStatusstringStatus de envio da campanha:
SENT – a campanha foi enviada;
DONE – a campanha foi concluída.
isDeletedintegerFlag indicando que a campanha foi excluída:
0 – a campanha está disponível;
1– a campanha foi excluída.
deferredToTsstringData e hora do envio agendado da campanha.
Formato: AAAA-MM-DD HH:MM:SS.
createTsstringData e hora de criação da campanha.
Formato: AAAA-MM-DD HH:MM:SS.
startSendTsstringData e hora do início real do envio da campanha.
Se o envio não tiver começado, este campo contém NULL.
Formato: AAAA-MM-DD HH:MM:SS.
endSendTsstringData e hora do término do envio de todas as mensagens da campanha.
Se o envio das mensagens não tiver sido concluído, este campo contém NULL.
Formato: AAAA-MM-DD HH:MM:SS.
namestringNome da campanha.
fromstringID do remetente que foi selecionado para o envio da campanha.
textstringTexto completo da mensagem ou texto de modelo com espaços reservados.
validityintegerTempo máximo de espera para entrega da mensagem, caso o destinatário não possa recebê-la imediatamente, em minutos a partir do momento do envio.
mclassintegerClasse da mensagem enviada:
0 – as mensagens são exibidas em uma janela pop-up e não são salvas em lugar nenhum (flashSMS);
1 – as mensagens são salvas na pasta de mensagens recebidas do telefone.
trackShortLinkRecipientsintegerSe a função de rastreamento de destinatários foi usada:
0 – a função não foi usada;
1 – a função foi usada.
groupsstringIdentificadores de grupos de contatos usados na campanha, separados por vírgulas.
globalCommentstringComentário do moderador, caso a campanha tenha sido recusada.
creationWayintegerMétodo de criação da campanha:
1 – via navegador de Internet;
5campanha funcional (de serviço).
countersarrayVários contadores da campanha, descritos na tabela Campos do objeto counters.
Campos do objeto counters
CampoTipoDescrição
updateTsdatetimeHora da última atualização dos contadores.
Para reduzir a carga no sistema, a atualização dos contadores pode ocorrer com atraso.
Formato: AAAA-MM-DD HH:MM:SS.
totalNewSegNumintegerNúmero total de segmentos com o status NEW.
totalAcceptdSegNumintegerNúmero total de segmentos com o status ACCEPTD.
totalDelivrdSegNumintegerNúmero total de segmentos com o status DELIVRD.
totalRejectdSegNumintegerNúmero total de segmentos com o status REJECTD.
totalExpiredSegNumintegerNúmero total de segmentos com o status EXPIRED.
totalUndelivSegNumintegerNúmero total de segmentos com o status UNDELIV.
totalDeletedSegNumintegerNúmero total de segmentos com o status DELETED.
totalUnknownSegNumintegerNúmero total de segmentos com o status UNKNOWN.
totalPdlivrdSegNumintegerNúmero total de segmentos com o status PDLIVRD.
totalSegNumintegerNúmero total de segmentos na campanha. Atualizado ao adicionar destinatários.
totalNewMsgNumintegerNúmero total de mensagens com o status NEW.
totalAcceptdMsgNumintegerNúmero total de mensagens com o status ACCEPTD.
totalDelivrdMsgNumintegerNúmero total de mensagens com o status DELIVRD.
totalRejectdMsgNumintegerNúmero total de mensagens com o status REJECTD.
totalExpiredMsgNumintegerNúmero total de mensagens com o status EXPIRED.
totalUndelivMsgNumintegerNúmero total de mensagens com o status UNDELIV.
totalDeletedMsgNumintegerNúmero total de mensagens com o status DELETED.
totalUnknownMsgNumintegerNúmero total de mensagens com o status UNKNOWN.
totalPdlivrdMsgNumintegerNúmero total de mensagens com o status PDLIVRD.
totalMsgNumintegerNúmero total de mensagens (não segmentos). Atualizado durante o processamento (antes do envio) das mensagens/segmentos da campanha.
totalNewMsgCostfloatCusto total de todos os segmentos com o status NEW.
totalAcceptdMsgCostfloatCusto total de todos os segmentos com o status ACCEPTD.
totalDelivrdMsgCostfloatCusto total de todos os segmentos com o status DELIVRD.
totalRejectdMsgCostfloatCusto total de todos os segmentos com o status REJECTD.
totalExpiredMsgCostfloatCusto total de todos os segments com o status EXPIRED.
totalUndelivMsgCostfloatCusto total de todos os segments com o status UNDELIV.
totalDeletedMsgCostfloatCusto total de todos os segments com o status DELETED.
totalUnknownMsgCostfloatCusto total de todos os segments com o status UNKNOWN.
totalPdlivrdMsgCostfloatCusto total de todos os segments com o status PDLIVRD.
totalCostfloatCusto total da campanha.
recipientsRejectedintegerNúmero de destinatários rejeitados (não incluídos na campanha). Atualizado ao adicionar destinatários.

Examples

curl -X POST \
  'https://api.mobizon.com.br/service/campaign/getInfo?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'id=123'
var data = "id=123";

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/campaign/getInfo?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(
    'campaign',
    'getInfo',
    array(
        //identificador da campanha
        'id' => '123'
    )
)
) {
    // 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 campanhas

https://api.mobizon.com.br/service/Campaign/List

Este método permite obter uma lista de campanhas criadas. A busca pode ser realizada por ID e outros campos.

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).

Critérios de busca

Abaixo estão listados os campos das campanhas pelos quais a busca é realizada. A busca pode ser realizada por um ou vários campos simultaneamente.

ParâmetroTipoDescrição
criteria[id]integerBusca de uma única campanha por seu ID.
criteria[ids]arrayBusca de várias campanhas por seus IDs.
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[recipient]stringBusca pelo número de telefone do destinatário ou parte dele.
Por 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[from]stringBusca pelo ID do remetente que foi usado na campanha.
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]stringBusca pelo status da campanha.
criteria[createTsFrom]stringBusca de campanhas criadas a partir da data e hora especificadas.
Formato: AAAA-MM-DD HH:MM:SS.
criteria[createTsTo]stringBusca de campanhas criadas até a data e hora especificadas.
Formato: AAAA-MM-DD HH:MM:SS.
criteria[sentTsFrom]stringBusca de campanhas cujo envio ocorreu a partir da data e hora especificadas.
Formato: AAAA-MM-DD HH:MM:SS.
criteria[sentTsTo]stringBusca de campanhas cujo envio ocorreu até a data e hora especificadas.
Formato: AAAA-MM-DD HH:MM:SS.
criteria[type]integerBusca pelo tipo de campanha:
1 – Mensagem única (envio para um número);
2 – Envio em massa (definido por padrão);
3 – Campanha de modelo (o texto da mensagem pode conter espaços reservados que serão substituídos por texto único para cada destinatário).
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.

Parâmetros de paginação

Estes parâmetros são destinados à 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 por data de criação da campanha em ordem crescente – sort[createTs]=ASC.
Ordenação por ID da campanha em ordem decrescente – sort[id]=DESC.

ParâmetroDescrição
sort[id]Ordenação pelo ID da campanha.
sort[name]Ordenação pelo nome da campanha.
sort[from]Ordenação pelo ID do remetente.
sort[counters.totalMsgNum]Ordenação pelo número de telefones da campanha.
sort[counters.totalCost]Ordenação pelo custo da campanha.
sort[createTs]Ordenação pela data e hora de criação da campanha.
sort[startSendTs]Ordenação pela data e hora de início do envio da campanha.
sort[endSendTs]Ordenação pela data e hora de término do envio da campanha.

Resposta do servidor

Contém um array com dois campos:

CampoTipoDescrição
itemsarrayLista das campanhas encontradas.
Consulte a descrição dos campos da campanha na descrição do método campaign/getInfo.
totalItemCountintegerNúmero total de elementos encontrados.
Status das campanhas
StatusDescrição
NEWA campanha foi criada, mas o usuário ainda não a enviou.
Neste status, a adição de destinatários é permitida.
MODERATIONPassando por moderação para conformidade com as regras do serviço.
DECLINEDRecusada pelo moderador, pois não cumpre as regras do serviço ou os requisitos das operadoras cujos números estão presentes na campanha.
READY_FOR_SENDA campanha está pronta para envio, mas o envio ainda não começou.
AUTO_READY_FOR_SENDNão há necessidade de moderação da campanha. A campanha será enviada sem moderação.
NOT_YET_SENTInclui todos os status em que a campanha ainda não foi enviada.
Este valor é usado apenas para busca. As campanhas não podem tê-lo.
RUNNINGA campanha foi iniciada, o processo de envio para a operadora está em andamento.
DEFERREDO envio da campanha está agendado para um horário específico.
Este valor é usado apenas para busca. As campanhas não podem tê-lo.
SENTA campanha foi totalmente enviada, mas nem todas as mensagens receberam relatório de entrega das operadoras.
DONEA campanha foi totalmente processada, todos os relatórios finais de entrega foram recebidos.
Após definir este status, nenhum contador da campanha é alterado.

Examples

curl -X POST \
  'https://api.mobizon.com.br/service/campaign/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%5Btype%5D=ASC'
var data = "criteria%5Bfrom%5D=Alpha&pagination%5BcurrentPage%5D=2&pagination%5BpageSize%5D=50&sort%5Btype%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/campaign/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(
    'campaign',
    '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 tipo de campanha
            'type' => '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 campanha

https://api.mobizon.com.br/service/Campaign/Send

Este método permite enviar uma campanha criada por seu ID.

Atenção! Dependendo das condições, como suspeita de spam, presença de conteúdo suspeito no texto da mensagem, restrição para uma determinada direção, etc., bem como das condições de cooperação (contrato assinado), a campanha pode passar por moderação.

Parâmetros da requisição

ParâmetroTipoDescrição
idintegerIdentificador da campanha.

Resposta do servidor

integer: status de envio da campanha.

Valores possíveis:

1 – a campanha está sendo verificada pelo moderador;
2 – a campanha foi enviada.

Códigos de resposta da API

CódigoDescrição
0Campanha enviada com sucesso.
2Se a campanha não for encontrada.
10Se não foi possível alterar o status da campanha.

Examples

curl -X POST \
  'https://api.mobizon.com.br/service/campaign/send?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'id=123'
var data = "id=123";

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/campaign/send?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(
    'campaign',
    'send',
    array(
        //identificador da campanha
        'id' => '123'
    )
)
) {
    // 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;
}