User Tools

Site Tools


br-040-send-message


Enviando mensagens para usuários

No Followzup, existem 3 formas de enviar mensagens. A primeira delas é conhecida como broadcast, que é utilizada quando se deseja enviar uma mensagem padrão para todos os assinantes do canal, sem exceção. A segunda forma é conhecida como unicast, que é utilizada quando se deseja enviar uma mensagem específica a um determinado assinante do canal, em particular. A terceira forma é conhecida como multicast, que é utilizada quando se deseja enviar uma mensagem padrão para um subconjunto de assinantes do canal.

Em um sistema de comércio eletrônico, por exemplo, podemos enviar mensagens do tipo broadcast contendo as ofertas da semana, indistintamente a todos os assinantes do canal, ou podemos também enviar uma mensagem do tipo unicast confirmando o pagamento de uma ordem de compra a um determinado usuário, em particular.

Mas digamos que o sistema de comércio eletrônico deseja agora enviar uma mensagem de broadcast contendo ofertas de roupas femininas, mas apenas ao subconjunto de assinantes do canal que sejam do sexo feminino, conforme consta em seu cadastro de clientes. Nesse caso, fazemos uso do tipo multicast, onde enviamos uma mensagem padrão para uma lista de usuários, extraídos da base de dados da loja.

No Followzup, uma mensagem de broadcast pode ser realizada com uma única solicitação ao webservice, enquanto que as mensagens unicast são realizadas uma a uma, até porque, são mensagens diferentes para cada destinatário. No caso das mensagens multicast, podemos realizar o envio de mensagens com listas de até 200 assinantes por solicitação.

É importante observar entretanto, que quando solicitamos o envio de mensagens unicast, devemos saber para quem estamos enviando. Dessa forma, quando enviamos uma mensagem para confirmar uma ordem de compra a um determinado cliente, devemos identificar o destinatário na hora de enviar a solicitação ao webservice. O mesmo ocorre quando precisamos construir uma lista de usuários para enviar uma mensagem do tipo multicast. Identificar o destinatário é nosso próximo assunto.



Identificando o destinatário

A identificação de destinatários para envio de mensagens unicast e multicast pode ser realizada de 2 formas: pelo e-mail do usuário ou pelo seu User-ID. A lista de destinatários em mensagens multicast pode misturar ambas as formas de identificação.

O User-ID é um código de 12 caracteres alfanuméricos iniciado com a letra “z”, e corresponde à identificação interna de cada usuário registrado no Followzup (exemplo: z4aw7cr23kmk). Todas as letras contidas em um User-ID são minúsculas.

Para a aplicação, não faz diferença enviar mensagens utilizando o e-mail ou o User-ID, mas para o destinatário, a diferença é a privacidade, como veremos no exemplo a seguir.

Digamos que em nossa loja virtual, o registro de cadastro de um determinado cliente, na base de dados da loja, contém seu e-mail. Com esse e-mail, a loja poderá enviar mensagens pelo Followzup e também poderá enviar mensagens pelo correio eletrônico. Se o cliente da loja deseja receber mensagens apenas pelo Followzup, poderá fazê-lo registrando seu User-ID no cadastro da loja, mas não informar seu e-mail. Nesse caso, a loja só poderá enviar mensagens por meio do Followzup.



Temporizando a mensagem

Um outro parâmetro fornecido pela aplicação quando a mensagem está sendo enviada é o tempo de vida da mensagem, limitado a 960 horas, equivalente a 40 dias.

Imagine que estamos numa sexta feira, e nossa loja virtual resolve fazer uma liquidação de calçados no fim de semana, e para tanto, envia de uma mensagem de broadcast para seus clientes. Em uma situação como essa, não faz sentido que um cliente que tenha deixado seu celular desligado durante o fim de semana, receba a mensagem na segunda feira, pois a liquidação já terá terminado. Para evitar que isso aconteça, a aplicação poderá limitar o tempo de vida da mensagem a uma quantidade de horas, suficiente para que os clientes recebam a mensagem a tempo de realizar suas compras. Os clientes que ligarem o celular após esse tempo de vida, simplesmente não recebem a mensagem.



Parametrizando a URL

Quando uma aplicação envia uma mensagem, pode-se, opcionalmente, informar um endereço HTTP associado a ela. Nesse caso, quando a mensagem é apresentada ao usuário, o APP habilita um link para a URL informada, permitindo que o usuário clique no texto da mensagem e abra a URL no navegador de seu dispositivo móvel.

Na forma mais simples, a URL pode apontar para um endereço qualquer, sem que exista a necessidade da aplicação saber quem foi o assinante que clicou na mensagem.

Mensagem Visite nossa página de ofertas da semana!
URL http://www.website.com/ofertas


Em um segundo caso, onde a aplicação necessita saber quem é o usuário, a URL pode incluir os parâmetros para sua identificação. Esses parâmetros são USERID e SUBSCODE, que são substituídos no texto da URL quando a mensagem é apresentada no dispositivo móvel.

Mensagem Seu pedido 12345 já foi enviado. Clique nessa mensagem e acompanhe o rastreamento de sua encomenda.
URL http://www.website.com?order=12345&user=USERID&subs=SUBSCODE

No exemplo acima, a aplicação receberá os parâmetros order, user e subs, contendo respectivamente o número do pedido (12345), o User-ID do usuário e o Código da Assinatura do canal. Uma vez que essa URL pode ser aberta por qualquer usuário na Internet (acidentalmente ou não), é importante que a aplicação faça a verificação do usuário informado (USERID e SUBSCODE). Essa verificação deve ser realizada com o comando chck (veja o tópico “Verificando usuários”).



Chamada da API para envio de mensagens

Para enviar mensagens, as aplicações devem usar o método submit contido na API, com seguintes parâmetros:

FZUP_COMMAND Obrigatório Deve conter a literal smsg (send message).
FZUP_LASTSEQ Opcional Contém o número de sequência da última solicitação.
FZUP_USER Obrigatório Contém o destinatário da mensagem:

- Literal “all”, para enviar mensagem a todos os assinantes (broadcast).

- E-mail ou User-ID do assinante, para enviar mensagem a um único destinatário (unicast).
Exemplos: “user.mail@anymail.com”, “z12h49d934jw”.

- Lista com até 200 e-mails ou User-IDs separados por vírgulas, para grupos de assinantes (multicast).
Exemplo: “user.mail@anymail.com,z12h49d934jw”.

FZUP_HOURS Opcional Deve conter um valor numérico entre 1 e 960, representando o tempo de vida da mensagem.
Para os valores inválidos ou não informados, o tempo de vida será definido em 24 horas.
FZUP_MSGTEXT Obrigatório Deve conter a mensagem a ser enviada, com até 200 caracteres.
FZUP_MSGURL Opcional Contém o endereço HTTP que será utilizado como “link” associado à mensagem, permitindo que o destinatário abra a URL informada ao clicar no texto da mensagem.



Exemplos em PHP:

Broadcast message
$result = $object -> submit ( array (
"FZUP_COMMAND = smsg",
"FZUP_LASTSEQ = 9999",
"FZUP_USER    = all",
"FZUP_HOURS   = 48",
"FZUP_MSGTEXT = This is a broadcast message.",
"FZUP_MSGURL  = http://www.website.com?user=USERID&subs=SUBSCODE" ) );
Unicast message to e-mail
$result = $object -> submit ( array (
"FZUP_COMMAND = smsg",
"FZUP_USER    = user.email@anymail.com",
"FZUP_MSGTEXT = This is a unicast message.",
"FZUP_MSGURL  = http://www.website.com/contact" ) );
Unicast message to User-ID
$result = $object -> submit ( array (
"FZUP_COMMAND = smsg",
"FZUP_USER    = ze87fh397a23",
"FZUP_MSGTEXT = This is a unicast message." ) );
Multicast message
$result = $object -> submit ( array (
"FZUP_COMMAND = smsg",
"FZUP_USER    = user.email@anymail.com,z85ghs574kfj",
"FZUP_MSGTEXT = This is a multicast message." ) );



Exemplos em JAVA:

Broadcast message
String[] result = object.submit ( new String[] {
"FZUP_COMMAND = smsg",
"FZUP_LASTSEQ = 9999",
"FZUP_USER    = all",
"FZUP_HOURS   = 48",
"FZUP_MSGTEXT = This is a broadcast message",
"FZUP_MSGURL  = http://www.website.com?user=USERID&subs=SUBSCODE" } );
Unicast message to e-mail
String[] result = object.submit ( new String[] {
"FZUP_COMMAND = smsg",
"FZUP_USER    = user.email@anymail.com",
"FZUP_MSGTEXT = This is a unicast message",
"FZUP_MSGURL  = http://www.website.com/contact" } );
Unicast message to User-ID
String[] result = object.submit ( new String[] {
"FZUP_COMMAND = smsg",
"FZUP_USER    = z74gd672kmv6",
"FZUP_MSGTEXT = This is a unicast message" } );
Multicast message
String[] result = object.submit ( new String[] {
"FZUP_COMMAND = smsg",
"FZUP_USER    = user.email@anymail.com,z74gd672kmv6",
"FZUP_MSGTEXT = This is a multicast message" } );



Exemplos em RUBY:

Broadcast message
result = object.submit (
"FZUP_COMMAND" => "smsg",
"FZUP_LASTSEQ" => "9999",
"FZUP_USER"    => "all",
"FZUP_HOURS"   => "48",
"FZUP_MSGTEXT" => "This is a broadcast message",
"FZUP_MSGURL"  => "http://www.website.com?user=USERID&subs=SUBSCODE" )
Unicast message to e-mail
result = object.submit (
"FZUP_COMMAND" => "smsg",
"FZUP_USER"    => "user.email@anymail.com",
"FZUP_MSGTEXT" => "This is a unicast message",
"FZUP_MSGURL"  => "http://www.website.com/contact" )
Unicast message to User-ID
result = object.submit (
"FZUP_COMMAND" => "smsg",
"FZUP_USER"    => "z74gd672kmv6",
"FZUP_MSGTEXT" => "This is a unicast message" )
Multicast message
result = object.submit (
"FZUP_COMMAND" => "smsg",
"FZUP_USER"    => "user.email@anymail.com,z74gd672kmv6",
"FZUP_MSGTEXT" => "This is a multicast message" )



Exemplos em PERL:

Broadcast message
my $result = $object->submit (
"FZUP_COMMAND = smsg",
"FZUP_LASTSEQ = 9999",
"FZUP_USER    = all",
"FZUP_HOURS   = 48",
"FZUP_MSGTEXT = This is a broadcast message",
"FZUP_MSGURL  = http://www.website.com?user=USERID&subs=SUBSCODE" );
Unicast message to e-mail
my $result = $object->submit (
"FZUP_COMMAND = smsg",
"FZUP_USER    = user.email@anymail.com",
"FZUP_MSGTEXT = This is a unicast message",
"FZUP_MSGURL  = http://www.website.com/contact" );
Unicast message to User-ID
my $result = $object->submit (
"FZUP_COMMAND = smsg",
"FZUP_USER    = z74gd672kmv6",
"FZUP_MSGTEXT = This is a unicast message" );
Multicast message
my $result = $object->submit (
"FZUP_COMMAND = smsg",
"FZUP_USER    = user.email@anymail.com,z74gd672kmv6",
"FZUP_MSGTEXT = This is a multicast message" );



Exemplos em PYTHON:

Broadcast message
result = object.submit([
"FZUP_COMMAND = smsg",
"FZUP_LASTSEQ = 9999",
"FZUP_USER    = all",
"FZUP_HOURS   = 48",
"FZUP_MSGTEXT = This is a broadcast message",
"FZUP_MSGURL  = http://www.website.com?user=USERID&subs=SUBSCODE"])
Unicast message to e-mail
result = object.submit([
"FZUP_COMMAND = smsg",
"FZUP_USER    = user.email@anymail.com",
"FZUP_MSGTEXT = This is a unicast message",
"FZUP_MSGURL  = http://www.website.com/contact"])
Unicast message to User-ID
result = object.submit([
"FZUP_COMMAND = smsg",
"FZUP_USER    = z74gd672kmv6",
"FZUP_MSGTEXT = This is a unicast message"])
Multicast message
result = object.submit([
"FZUP_COMMAND = smsg",
"FZUP_USER    = user.email@anymail.com,z74gd672kmv6",
"FZUP_MSGTEXT = This is a multicast message"])



Retorno da execução

Nos exemplos anteriores, podemos verificar que a execução do método submit retorna um array de strings denominado result. Esse array possui 3 elementos:

Código de retorno Código de retorno da solicitação, sendo o valor “0” (zero) para as solicitações executadas com sucesso e o valor “NNNN” contendo o código de erro da execução.
Número de sequência Valor inteiro contendo o número de sequência utilizado na solicitação.
XML de resposta da solicitação String contendo o XML de resposta da solicitação.

Com exceção do código de retorno 6101, tratado pela API, os demais erros devem ser tratados pela aplicação.

É importante que o número de sequência utilizado na última solicitação seja armazenado na base de dados da aplicação, para o caso do objeto instanciado ter sido descartado pelo ambiente. Dessa forma, a última sequência poderá ser informada para a API na próxima solicitação e evitar que a API receba códigos de erro 6101, forçando o reenvio de solicitações e aumentando o tempo de resposta das solicitações.



Códigos de retorno

0 Execução com sucesso Informa que a solicitação foi realizada com sucesso, mesmo que algum dos destinatários informados tenha sido considerado inválido
6101 Sequência inválida Esse código de retorno é tratado pela API
6102 Frame inválido Informa que houve erro na decriptação dos dados, podendo ter ocorrido falha na transmissão
6103 Comando inválido Comando inválido ou não foi informado
6104 Channel-ID inválido Channel-ID inválido ou não foi informado
6108 Mensagem inválida Mensagem nula ou maior do que 200 caracteres
6109 Lista muito grande A lista de destinatários informada possui mais de 200 entradas
6110 URL inválida URL inválida ou maior do que 200 caracteres
6999 Sistema em manutenção Webservice encontra-se em manutenção



XML de resposta da solicitação

<?xml version="1.0" encoding="utf-8"?>
<followzup>
  <snt>total-sent</snt>
  <nsb>total-no-subs</nsb>
  <inv>total-invalid</inv>
</followzup>

Onde:
 - Total-sent:    Total de mensagens enviadas.
 - Total-no-subs: Total de destinatários informados na solicitação que não são assinantes do canal.
 - Total-invalid: Total de destinatários informados na solicitação que foram considerados inválidos. 



Mensagens antigas

As mensagens enviadas pelas aplicações permanecem na base de dados do Followzup aguardando que um dispositivo do assinante estabeleça conexão com o webservice. Nesse momento, as mensagens são transferidas para o dispositivo onde poderão ser lidas.

Essa transferência de mensagens obedece uma regra básica associada à verificação da vida útil da mensagem, ou seja, se o assinante ligar seu dispositivo após expirar a vida útil da mensagem, ela simplesmente não é transferida. Entretanto, existem situações onde o próprio Followzup modifica o tempo de vida útil das mensagens, como veremos a seguir.

Digamos que uma aplicação envia uma mensagem com vida útil de 15 dias para um assinante que possui 2 dispositivos móveis, mas apenas um deles está ligado. Nesse caso, quando o primeiro dispositivo recebe a mensagem, a vida útil da mensagem é reduzida para 24 horas. Essa característica do Followzup tem por objetivo impedir que dispositivos desligados há muito tempo recebam uma avalanche de mensagens antigas já recebidas por dispositivos conectados. Essa redução de vida útil só não é realizada quando o tempo de vida útil de uma mensagem já é menor do que 24 horas.


br-040-send-message.txt · Last modified: 2017/04/20 16:09 by admin

Page Tools