Hungary Web-Initiated Subscriptions

This document is designed to help you integrate web-initiated subscriptions into your application. Before you begin, you will need to contact MessageCloud's support team via help@messagecloud.com to register your keyword.

Overview

The below diagram shows the expected flow of messages in the process.

The customer visits merchant's website and enters their MSISDN.
The merchant sends a free welcome message to the customer via MessageCloud, containing the price, length and interval of the subscription.
MessageCloud sends a double opt-in confirmation MT to the customer.
The customer replies to the double opt-in request with IGEN.
MessageCloud activates the subscription and forwards the original welcome message to the customer.
MessageCloud sends a SUBSCRIBED delivery report to the merchant.
The merchant sends chargeable MT messages to the customer via MessageCloud at the subscription intervals defined in the welcome message.
MessageCloud notifies the merchant of charging success or failure with a delivery report.
The customer can opt out of the subscription by sending STOP [KEYWORD].
A notification of opt-out is sent to the merchant
The merchant sends a free confirmation of opt-out message to the customer. If this is not sent within 30 seconds of receipt then MessageCloud will reply on your behalf.

Integration Details

The following section details how you can achieve the MO-initiated subscription model using Gateway . Due to the nature of Hungary's message flow, there are some extra parameters you should send to the API in certain circumstances.

Firstly, when the customer opts into your subscription service, they will be sent a free message by MessageCloud asking them to confirm the opt-in. Only after the customer has confirmed this opt-in will the original message be forwarded to you as detailed in Receiving a Message. It is at this point you should send the customer a welcome message.

Sending a Welcome Message

You should send a request to Gateway using the parameters listed on Sending a Message, but the following parameters should be set accordingly:

Variable	Type	Contents
`reply`	Integer	`0`
`id`	String	This needs to be blank
`value`	Float	`0.00`
`currency`	String	`HUF`
`command`	String	`W` (where `W` stands for Welcome message)
`sub_url`	String	The location of the opt-in MSISDN entry form
`sub_ip`	String	The customer's IP address
`sub_key`	String	The keyword used for the subscription service. This is provided by MessageCloud on application.

You should receive a SUCCESS in the body of the HTTP response if everything was successful.

Sending a Content Message

Now that the welcome message is sent to the customer, you can send your subscription content messages according to your agreed subscription interval.

Variable	Type	Contents
`reply`	Integer	`0`
`id`	String	The format of the `id` string should be `[message_id]\|[your_callback_id]` , where `[message_id]` is the value of `message_id` you received in the `report=SUBSCRIBED` delivery report and `[your_callback_id]` is the ID of the message in your platform. If you do not wish to use `[your_callback_id]` , you should set this to a random string.
`value`	Float	The value of your subscription content message.
`currency`	String	`HUF`

Sending a Goodbye Message

When the customer opts out of your subscription service, you will be sent an MO containing the word STOP according to the information provided on Stop Requests.

From the time you receive the MO, you will have 30 seconds in which to reply with your goodbye message otherwise MessageCloud will automatically send one on your behalf.

The following parameters should be sent to Gateway, in addition to the required parameters detailed on Sending a Message:

Variable	Type	Contents
`reply`	Integer	`0`
`id`	String	The format of the `id` string should be `[message_id]\|[your_callback_id]` , where `[message_id]` is the value of `message_id` you received in the `report=SUBSCRIBED` delivery report and `[your_callback_id]` is the ID of the message in your platform. If you do not wish to use `[your_callback_id]` , you should set this to a random string.
`value`	Float	`0.00`
`currency`	String	`HUF`
`command`	String	`G` (where `G` stands for Goodbye message)

You will receive a SUCCESS in the body of the HTTP response if the request was successful.