User Tools

Site Tools


en-040-send-message


Sending messages to users

In Followzup there are 3 ways to send messages. The first one is known as broadcast, which is used when you want to send a standard message to all channel subscribers, with no exception. The second form is known as unicast, which is used when it is desired to send a specific message to a particular channel subscriber. The third form is known as multicast, which is used when it is desired to send a standard message to a subset of channel subscribers.

In an e-commerce system, for example, we can send broadcast messages containing the offers of the week, indistinctly to all subscribers of the channel, or we can also send a message of the unicast type confirming the payment of a purchase order to a user in particular.

But let's just say that the e-commerce system now wants to send a broadcast message containing offers of women's clothing, but only to the subset of female channel subscribers as it appears in their customer database. In this case, we use the multicast type, where we send a default message to a list of users, extracted from the its database.

In Followzup, a broadcast message can be performed with a single request to the webservice, whereas unicast messages are performed one by one, because they are different messages for each receiver. In the case of multicast messages, we can send messages with lists of up to 200 subscribers per request.

It is important to note however that when requesting the sending of unicast messages, we must know to whom we are sending. That way, when we send a message to confirm a purchase order to a particular customer, we must identify the receiver to send the request to the webservice. The same thing happens when we need to build a list of users to send a multicast message. Identifying the receiver is our next subject.



Identifying the receiver

The identification of receivers to send unicast and multicast messages can be done in two ways: by the user's email or by its User-ID. The list of receivers in multicast messages can mix both forms of identification.

The User-ID is a 12-character alphanumeric code beginning with the letter “z”, and corresponds to the internal identification of each user registered in Followzup (example: z4aw7cr23kmk). All letters contained in a User-ID are lowercase.

For the application, it makes no difference to send messages using the email or the User-ID, but for the receiver, the difference is privacy, as we will see in the following example.

Let's say that in our online store, the registration of a particular customer's record into the database contains his email. With this email, the online store can send messages through Followzup and you can also send messages by e-mail. If the customer wants to receive messages only through Followzup, he can do it by registering his User-ID in the store's database, but not informing his e-mail. In this case, the online store could only send messages through Followzup.



Timing the message

Another parameter provided by the application when the message is being sent is the message lifetime, limited to 960 hours, equivalent to 40 days.

Imagine that we are on Friday, and our online store resolves to do a shoes clearance over the weekend, and for that, it sends a broadcast message to its customers. In a situation like this, it does not make sense for a customer who has left his cell phone off during the weekend, get the message on Monday, because the settlement is over. To prevent this from happening, the application can limit the lifetime of the message to a quantity of hours, enough for customers to receive the message in time to make their purchases. Customers who turn on their cell phone after this lifetime simply do not receive the message.



Parametrizing the URL

When an application sends a message, you can optionally enter an HTTP address associated with it. In this case, when the message is presented to the user, the APP enables a link to the entered URL, allowing the user to click on the message text and open the URL in the browser of their mobile device.

In the simplest way, the URL can point to an URL, without there being any need for the application to know who has clicked on the message.

Message Visit our page of offers of the week!
URL http://www.website.com/offers


In a second case, where the application needs to know who the user is, the URL can include the parameters for their identification. These parameters are USERID and SUBSCODE, which are replaced in the URL text when the message is displayed on the mobile device.

Message Your request 12345 has already been sent. Click on this message and track your order.
URL http://www.website.com?order=12345&user=USERID&subs=SUBSCODE

In the example above, the application will receive the parameters order, user and subs, containing the order number (12345), the User-ID and the Subscription Code . Since this URL can be opened by any user on the Internet (accidentally or not), it is important that the application perform the user verification informed (USERID and SUBSCODE). This check must be performed with the command chck (see the topic “ Checking Users”).



API call for sending messages

To send messages, applications must use the submit method contained in the API, with the following parameters:

FZUP_COMMAND Required Must contain the literal smsg (send message).
FZUP_LASTSEQ Optional Contains the sequence number of the last request.
FZUP_USER Required Contains the receiver of the message:

- Literal “all”, to send message to all subscribers (broadcast).

- E-mail or User-ID of the subscriber, to send message to a single receiver (unicast).
Examples: “user.amil@anymail.com” or “z12h49d934jw”.

- List with up to 200 emails or User-IDs separated by commas, for subscriber groups (multicast).
Example: “user.amil@anymail.com,z12h49d934jw”.

FZUP_HOURS Optional It must contain a numerical value between 1 and 960, representing the lifetime of the message.
For invalid or unreported values, lifetime is set to 24 hours.
FZUP_MSGTEXT Required It must contain the message to be sent, up to 200 characters.
FZUP_MSGURL Optional Contains the HTTP address that will be used as the link associated with the message, allowing the receiver to open the given URL by clicking on the message text.



Examples in 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." ) );



Examples in 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" } );



Examples in 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" )



Examples in 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" );



Examples in 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"])



Examples in C# .NET:

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



Return of execution

In the previous examples, we can see that the execution of the submit method returns an array of strings named as result. This array has 3 elements:

Return code The return code of the request. The value “0” (zero) for successfully executed requests and the value “NNNN” containing the execution error code.
Sequence number Integer value containing the sequence number used in the request.
XML request response The string containing the XML request response.

With the exception of return code 6101, handled by the API, other errors must be handled by the application.

It is important that the sequence number used in the last request to be stored in the application database, in case the instantiated object has been discarded by the environment. The last sequence stored can be informed to the API, preventing the API from receiving 6101 error codes, forcing requests to be rescheduled and increasing response times for requests.



Return codes

0 Successful execution Informs that the request has been successful, even any of the receivers informed were considered invalid
6101 Invalid sequence This return code is handled by the API
6102 Invalid frame Informs that there was an error in the decryption of the data, and transmission may have failed
6103 Invalid command Command was invalid or not informed
6104 Invalid Channel-ID Channel-ID was invalid or not informed
6108 Null message Message reported is null
6109 Very large list The list of receivers has more than 200 entries
6999 System in maintenance Webservice is out of service



XML request response

<?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 sent messages.
 - Total-no-subs: Total receivers informed in the request that are not channel subscribers.
 - Total-invalid: Total receivers reported in the request that were considered invalid. 



Old messages

Messages sent by applications remain in the Followzup database waiting for a subscriber device to connect to the webservice. At this point, the messages are transferred to the device where they can be read.

This message transfer obeys a basic rule associated with verifying message life, that is, if the subscriber turns on their device after the message has expired, it is simply not transferred. However, there are situations where Followzup itself modifies the lifetime of messages, as we will see below.

Let's say an application sends a 15-day lifetime message to a subscriber who has 2 mobile devices, but only one of them is turned on. In this case, when the first device receives the message, the message lifetime is reduced to 24 hours. This feature of Followzup aims to prevent long-disconnected devices from receiving a lot of old messages already received by connected devices. This reduction is not realized when the lifetime of the message is already less than 24 hours.

en-040-send-message.txt · Last modified: 2017/06/27 21:01 by admin

Page Tools