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.
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
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:
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:
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âmetro | Tipo | Descrição |
|---|---|---|
id | integer | Identificador da campanha na qual os destinatários devem ser adicionados. |
recipients | array string | Para um envio normal (sem o uso de variáveis placeholder no texto), os destinatários podem ser passados como:
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). |
recipientContacts | array string | Array ou string de contatos da agenda de contatos separados por vírgulas ou quebras de linha. Um contato pode ser especificado como:
|
recipientGroups | array string | Array 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. |
recipientsFile | file | Objeto 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). |
params | array | Configurações adicionais (veja a tabela Configurações Adicionais). |
| Parâmetro | Tipo | Descrição |
|---|---|---|
params[replace] | integer | Indica 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] | integer | Processamento 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] | string | Codificaçã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] | integer | Indica 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] | string | Separador 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] | string | Delimitador 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. |
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:
| Campo | Tipo | Descrição |
|---|---|---|
recipient | string | Número do destinatário que está sendo adicionado à campanha. |
code | integer | Có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 |
messageId | integer | Identificador da mensagem adicionada, se o número foi adicionado, o status da mensagem pode ser obtido pelo identificador especificado. |
number | integer | O valor original do número do destinatário passado pelo usuário (se o número do destinatário foi passado). |
contact | integer | Identificador 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ódigo | Descrição |
|---|---|
| 1 | Se algum parâmetro contiver valores inválidos. |
| 2 | Se a campanha com o ID especificado não for encontrada. |
| 10 | Se 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. |
| 12 | Se nenhum tipo de destinatário for passado ou se vários tipos de destinatários forem passados em uma única requisição. |
| 98 | Se, de todos os destinatários passados, pelo menos um não tiver sido adicionado à campanha. |
| 99 | Se nenhum destinatário tiver sido adicionado à campanha como resultado da execução da requisição. |
| 100 | Se uma tarefa de segundo plano para adicionar destinatários foi iniciada. Detalhes sobre o trabalho com tarefas em segundo plano veja aqui. |
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.
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).
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.
data array – Parâmetros da campanha
| Parâmetro | Tipo | Descrição |
|---|---|---|
data[name] | string | Nome 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] | string | Texto 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] | integer | Tipo 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] | string | ID 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] | integer | O 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] | integer | O 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] | string | Data 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] | integer | O 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] | integer | Encurtar links no texto - 1, padrão não encurtar - 0. |
data[trackShortLinkRecipients] | integer | Recurso 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. |
integer – identificador da campanha, se for criada com sucesso.
| Código | Descrição |
|---|---|
| 0 | A campanha foi criada com sucesso. |
| 1 | Se algum parâmetro contiver valores inválidos. |
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;
}
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âmetro | Tipo | Descrição |
|---|---|---|
id | integer | Identificador da campanha. |
| Código | Descrição |
|---|---|
| 0 | Campanha excluída com sucesso. |
| 2 | Se a campanha com o identificador especificado não for encontrada. |
| 10 | Se a campanha com o identificador especificado não puder ser excluída. |
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;
}
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âmetro | Tipo | Descrição |
|---|---|---|
id | integer | Identificador da campanha. |
Um array de dados contendo os seguintes campos:
| Campo | Tipo | Descrição |
|---|---|---|
id | string | Identificador da campanha. |
moderationStatus | string | Status 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. |
commonStatus | string | Status 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. |
groupsList | array | Lista 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. |
type | integer | Tipo de campanha: 1 – Mensagem única (enviada para um número); 2 – Envio em massa; 3 – Campanha de modelo; 7 – Campanha funcional (de serviço). |
msgType | string | Tipo de mensagens da campanha. Atualmente, apenas o tipo "SMS" é suportado. |
rateLimit | integer | Limite do número de mensagens enviadas no período especificado no campo ratePeriod. |
ratePeriod | integer | Período de tempo em segundos durante o qual o número de SMS especificado no campo rateLimit será enviado. |
sendStatus | string | Status de envio da campanha: SENT – a campanha foi enviada; DONE – a campanha foi concluída. |
isDeleted | integer | Flag indicando que a campanha foi excluída: 0 – a campanha está disponível; 1 – a campanha foi excluída. |
deferredToTs | string | Data e hora do envio agendado da campanha. Formato: AAAA-MM-DD HH:MM:SS. |
createTs | string | Data e hora de criação da campanha. Formato: AAAA-MM-DD HH:MM:SS. |
startSendTs | string | Data e hora do início real do envio da campanha. Formato: AAAA-MM-DD HH:MM:SS. |
endSendTs | string | Data e hora do término do envio de todas as mensagens da campanha. Formato: AAAA-MM-DD HH:MM:SS. |
name | string | Nome da campanha. |
from | string | ID do remetente que foi selecionado para o envio da campanha. |
text | string | Texto completo da mensagem ou texto de modelo com espaços reservados. |
validity | integer | Tempo 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. |
mclass | integer | Classe 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. |
trackShortLinkRecipients | integer | Se a função de rastreamento de destinatários foi usada: 0 – a função não foi usada; 1 – a função foi usada. |
groups | string | Identificadores de grupos de contatos usados na campanha, separados por vírgulas. |
globalComment | string | Comentário do moderador, caso a campanha tenha sido recusada. |
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;
}
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âmetro | Tipo | Descrição |
|---|---|---|
id | integer | Identificador da campanha. |
getFilledTplCampaignText | integer | Formato 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). |
| Campo | Tipo | Descrição |
|---|---|---|
id | integer | Identificador da campanha. |
moderationStatus | string | Status 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. |
commonStatus | string | Status 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. |
groupsList | array | Lista 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. |
type | integer | Tipo de campanha: 1 – Mensagem única (enviada para um número); 2 – Envio em massa; 3 – Campanha de modelo; 7 – Campanha funcional (de serviço). |
msgType | string | Tipo de mensagens da campanha. Atualmente, apenas o tipo "SMS" é suportado. |
rateLimit | integer | Limite do número de mensagens enviadas no período especificado no campo ratePeriod. |
ratePeriod | integer | Período durante o qual o número de SMS especificado no campo rateLimit será enviado. |
sendStatus | string | Status de envio da campanha: SENT – a campanha foi enviada; DONE – a campanha foi concluída. |
isDeleted | integer | Flag indicando que a campanha foi excluída: 0 – a campanha está disponível; 1– a campanha foi excluída. |
deferredToTs | string | Data e hora do envio agendado da campanha. Formato: AAAA-MM-DD HH:MM:SS. |
createTs | string | Data e hora de criação da campanha. Formato: AAAA-MM-DD HH:MM:SS. |
startSendTs | string | Data 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. |
endSendTs | string | Data 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. |
name | string | Nome da campanha. |
from | string | ID do remetente que foi selecionado para o envio da campanha. |
text | string | Texto completo da mensagem ou texto de modelo com espaços reservados. |
validity | integer | Tempo 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. |
mclass | integer | Classe 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. |
trackShortLinkRecipients | integer | Se a função de rastreamento de destinatários foi usada: 0 – a função não foi usada; 1 – a função foi usada. |
groups | string | Identificadores de grupos de contatos usados na campanha, separados por vírgulas. |
globalComment | string | Comentário do moderador, caso a campanha tenha sido recusada. |
creationWay | integer | Método de criação da campanha: 1 – via navegador de Internet; 5 – campanha funcional (de serviço). |
counters | array | Vários contadores da campanha, descritos na tabela Campos do objeto counters. |
counters| Campo | Tipo | Descrição |
|---|---|---|
updateTs | datetime | Hora 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. |
totalNewSegNum | integer | Número total de segmentos com o status NEW. |
totalAcceptdSegNum | integer | Número total de segmentos com o status ACCEPTD. |
totalDelivrdSegNum | integer | Número total de segmentos com o status DELIVRD. |
totalRejectdSegNum | integer | Número total de segmentos com o status REJECTD. |
totalExpiredSegNum | integer | Número total de segmentos com o status EXPIRED. |
totalUndelivSegNum | integer | Número total de segmentos com o status UNDELIV. |
totalDeletedSegNum | integer | Número total de segmentos com o status DELETED. |
totalUnknownSegNum | integer | Número total de segmentos com o status UNKNOWN. |
totalPdlivrdSegNum | integer | Número total de segmentos com o status PDLIVRD. |
totalSegNum | integer | Número total de segmentos na campanha. Atualizado ao adicionar destinatários. |
totalNewMsgNum | integer | Número total de mensagens com o status NEW. |
totalAcceptdMsgNum | integer | Número total de mensagens com o status ACCEPTD. |
totalDelivrdMsgNum | integer | Número total de mensagens com o status DELIVRD. |
totalRejectdMsgNum | integer | Número total de mensagens com o status REJECTD. |
totalExpiredMsgNum | integer | Número total de mensagens com o status EXPIRED. |
totalUndelivMsgNum | integer | Número total de mensagens com o status UNDELIV. |
totalDeletedMsgNum | integer | Número total de mensagens com o status DELETED. |
totalUnknownMsgNum | integer | Número total de mensagens com o status UNKNOWN. |
totalPdlivrdMsgNum | integer | Número total de mensagens com o status PDLIVRD. |
totalMsgNum | integer | Número total de mensagens (não segmentos). Atualizado durante o processamento (antes do envio) das mensagens/segmentos da campanha. |
totalNewMsgCost | float | Custo total de todos os segmentos com o status NEW. |
totalAcceptdMsgCost | float | Custo total de todos os segmentos com o status ACCEPTD. |
totalDelivrdMsgCost | float | Custo total de todos os segmentos com o status DELIVRD. |
totalRejectdMsgCost | float | Custo total de todos os segmentos com o status REJECTD. |
totalExpiredMsgCost | float | Custo total de todos os segments com o status EXPIRED. |
totalUndelivMsgCost | float | Custo total de todos os segments com o status UNDELIV. |
totalDeletedMsgCost | float | Custo total de todos os segments com o status DELETED. |
totalUnknownMsgCost | float | Custo total de todos os segments com o status UNKNOWN. |
totalPdlivrdMsgCost | float | Custo total de todos os segments com o status PDLIVRD. |
totalCost | float | Custo total da campanha. |
recipientsRejected | integer | Número de destinatários rejeitados (não incluídos na campanha). Atualizado ao adicionar destinatários. |
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;
}
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â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). |
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âmetro | Tipo | Descrição |
|---|---|---|
criteria[id] | integer | Busca de uma única campanha por seu ID. |
criteria[ids] | array | Busca 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] | string | Busca 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] | string | Busca pelo ID do remetente que foi usado na campanha. |
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] | string | Busca pelo status da campanha. |
criteria[createTsFrom] | string | Busca de campanhas criadas a partir da data e hora especificadas. Formato: AAAA-MM-DD HH:MM:SS. |
criteria[createTsTo] | string | Busca de campanhas criadas até a data e hora especificadas. Formato: AAAA-MM-DD HH:MM:SS. |
criteria[sentTsFrom] | string | Busca de campanhas cujo envio ocorreu a partir da data e hora especificadas. Formato: AAAA-MM-DD HH:MM:SS. |
criteria[sentTsTo] | string | Busca de campanhas cujo envio ocorreu até a data e hora especificadas. Formato: AAAA-MM-DD HH:MM:SS. |
criteria[type] | integer | Busca 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] | 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. |
Estes parâmetros são destinados à 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 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âmetro | Descriçã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. |
Contém um array com dois campos:
| Campo | Tipo | Descrição |
|---|---|---|
items | array | Lista das campanhas encontradas. Consulte a descrição dos campos da campanha na descrição do método campaign/getInfo. |
totalItemCount | integer | Número total de elementos encontrados. |
| Status | Descrição |
|---|---|
| NEW | A campanha foi criada, mas o usuário ainda não a enviou. Neste status, a adição de destinatários é permitida. |
| MODERATION | Passando por moderação para conformidade com as regras do serviço. |
| DECLINED | Recusada 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_SEND | A campanha está pronta para envio, mas o envio ainda não começou. |
| AUTO_READY_FOR_SEND | Não há necessidade de moderação da campanha. A campanha será enviada sem moderação. |
| NOT_YET_SENT | Inclui 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. |
| RUNNING | A campanha foi iniciada, o processo de envio para a operadora está em andamento. |
| DEFERRED | O envio da campanha está agendado para um horário específico. Este valor é usado apenas para busca. As campanhas não podem tê-lo. |
| SENT | A campanha foi totalmente enviada, mas nem todas as mensagens receberam relatório de entrega das operadoras. |
| DONE | A campanha foi totalmente processada, todos os relatórios finais de entrega foram recebidos. Após definir este status, nenhum contador da campanha é alterado. |
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;
}
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âmetro | Tipo | Descrição |
|---|---|---|
id | integer | Identificador da campanha. |
integer: status de envio da campanha.
1 – a campanha está sendo verificada pelo moderador;
2 – a campanha foi enviada.
| Código | Descrição |
|---|---|
| 0 | Campanha enviada com sucesso. |
| 2 | Se a campanha não for encontrada. |
| 10 | Se não foi possível alterar o status da campanha. |
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;
}