Cyprus – CYTA PIN Opt-in Subscriptions

Cyprus – CYTA PIN Opt-in Subscriptions

The information provided in this document is intended for developers to integrate the subscription and charging of your customers who are registered with the CYTA network in Cyprus using a PIN opt-in flow. If you have not already done so, please contact the business development team before attempting to follow this guide; business@messagecloud.com or +44 (0)330 1130 243, option 2.

Flow diagram

Explanation of flow diagram

1. You must register your application with a service keyword by contacting us.
2. Customer visits your website and enters their phone number into a form.
3. You send a request to our generate-pin API. Customer is redirected to a verify PIN form.
4. CYTA sends a free SMS to the customer containing a PIN and information about the service to which they are subscribing.
5. Customer enters PIN into your website.
6. You send the PIN to our verify-pin API.
7. Once verified, the customer is sent a free SMS by CYTA requiring them to reply with the text OK to complete the opt-in.
8. Customer replies to this SMS with the aforementioned message.
9. MessageCloud forwards an MO notification to you to confirm that a successful opt-in has taken place.
10. You can now send a chargeable MT to the customer via our Gateway API.
11. If customer requests an opt-out, we will send this to you as an MO notification. You can also manually invoke an opt-out by calling the stop API.

Registering your campaign

To register your campaign with CYTA, please contact the support team through help@messagecloud.com. You will need to provide them with a service keyword which will represent your service and will be seen by your customers. You may also be required to provide any relevant promotional material for your campaign.

Generating a PIN

To start the opt-in process, you should obtain the MSISDN of the customer and call the API with the following parameters. Please note that all parameters are required.

Your requests should be sent to:

https://client.txtnation.com/cy/generate-pin

You are able to send either HTTP GET or HTTP POST to this API.

If we called the API with an HTTP GET, the request might look as follows:

$ curl -v "https://client.txtnation.com/cy/generate-pin?campaign_name=XXXX&api_key=XXXX&network=cyta&service=TEST&msisdn=35700000000"
> GET /cy/generate-pin?campaign_name=XXXX&api_key=XXXX&network=cyta&service=TEST&msisdn=35700000000 HTTP/1.1
> Host: client.txtnation.com
> User-Agent: curl/7.64.1
> Accept: */*
>
< HTTP/1.1 200 OK
< X-Served-By: Eos
< Content-type: text/html; charset=UTF-8
< Content-Length: 109
< Date: Mon, 16 Dec 2019 16:53:24 GMT
< Server: txtNation HTTP Server
<
{"success":true,"statusCode":0,"statusMessage":"Pin Sent","requestId":"d827f300-624a-48b1-89e8-d0e19d71287b"}

Successful requests will be responded to with a JSON-formatted object containing a boolean status value of true. An example of this is shown below:

{"success":true,"statusCode":0,"statusMessage":"Pin Sent","requestId":"d827f300-624a-48b1-89e8-d0e19d71287b"}

From this result, it is important to store the requestId so that you can use it in the next step once the PIN has been submitted by the customer.

Failed responses will contain a non-zero status code in the statusCode parameter, with a relevant message in the statusMessage parameter. For your convenience, a list of potential status codes are provided in Status Codes.

At this point, an SMS will be sent to the customer containing a PIN in a format similar to the below:

6272  
KΩΔIKOΣ EΓΓPAΦHΣ ΣTH XPEΩΣIMH ΣYNΔPOMHTIKH YΠHPEΣIA TEST. H XPEΩΣH ANAΦEPETAI ΣTHN IΣTOΣEΛIΔA: txtNation - https://www.txtnation.com/. BEBAIΩΣOY OTI EXEIΣ ΔIABAΣEI ΠPOΣEKTIKA TOYΣ OPOYΣ

Verifying a PIN

When a customer has entered their PIN code into the form on your website, the following API will verify it for you. Once sent, the customer has approximately 2-3 minutes to confirm the PIN before they receive a second message informing them that they were not opted in quickly enough. At this point, the customer can restart the opt-in process.

Your requests should be sent to:

https://client.txtnation.com/cy/verify-pin

You are able to send either HTTP GET or HTTP POST to this API.

If we called the API with an HTTP GET, the request might look as follows:

$ curl -v "https://client.txtnation.com/cy/verify-pin?campaign_name=XXXX&api_key=XXXX&network=cyta&id=d827f300-624a-48b1-89e8-d0e19d71287b&pin=1234"
> GET /cy/verify-pin?campaign_name=XXXX&api_key=XXXX&network=cyta&id=d827f300-624a-48b1-89e8-d0e19d71287b&pin=1234 HTTP/1.1
> Host: client.txtnation.com
> User-Agent: curl/7.64.1
> Accept: */*
>
< HTTP/1.1 200 OK
< X-Served-By: Eos
< Content-type: text/html; charset=UTF-8
< Content-Length: 67
< Date: Wed, 18 Dec 2019 12:01:24 GMT
< Server: txtNation HTTP Server
<
{"success":true,"statusCode":0,"statusMessage":"PIN Verified"}

Successful requests will be responded to with a JSON-formatted object containing a boolean status value of true. An example of this is shown below:

{"success":true,"statusCode":0,"statusMessage":"PIN Verified"}

Failed responses will contain a non-zero status code in the  statusCode parameter, with a relevant message in the statusMessage parameter. For your convenience, a list of potential status codes are provided in Status Codes.

Notification of opt-in

Once the PIN has been verified, the customer will be sent an SMS instructing them to reply with the message OK. The SMS will be in the following format:

ΣTEIΛE AΠANTHΣH ME TH ΛEΞH OK & EΠIBEBAIΩΣE THN ENTOΛH ΣOY ΓIA EΓΓPAΦH ΣTH ΣYNΔPOMHTIKH XPEΩΣIMH YΠHPEΣIA TEST THΣ ETAIPEIAΣ: txtNation
THΛ: 302111990759
TIMH: €2.03 ANA SMS

After the customer replies with OK they will receive a final SMS that confirms the subscription has started:

H EΓΓPAΦH OΛOKΛHPΩΘHKE ΣTH XPEΩΣIMH ΣYNΔPOMHTIKH YΠHPEΣIA TEST ME XPEΩΣH KAI OPOYΣ OΠΩΣ ANAΦEPONTAI ΣTHN IΣTOΣEΛIΔA THΣ YΠHPEΣIAΣ. ΓIA AΠENEPΓOΠOIHΣH ΣTEIΛE: OFF TEST ΣTON APIΘMO 6161. ΔYNATOTHTA YΠOBOΛHΣ ΠAPAΠONΩN
IΣTOΣEΛIΔEΣ
YΠΠ: https://www.txtnation.com
CYTA: https://www.cyta.com.cy

We will then send a notification of the MO to your chosen MO receiver using the same format and URL as supported by Gateway. You can read more about this in the Receiving a Message part of the Gateway documentation. All notifications relayed to you will have the following messages:

Sending a chargeable MT

Now the the customer has opted into your subscription, you are able to send your first premium MT SMS. This can be achieved by using Gateway. You can read more about this in the Sending a Message part of the Gateway documentation.

Opt-outs

There are two ways for the customer to opt-out of your subscription service; the customer can send OFF + your service to 8882 or you can trigger an opt-out by calling our stop API.

Your requests should be sent to:

https://client.txtnation.com/cy/stop

To use this API action you need to send an HTTP POST or GET with the following parameters:

If we called the API with an HTTP GET, the request might look as follows:

$ curl -v "https://client.txtnation.com/cy/stop?campaign_name=XXXX&api_key=XXXX&network=cyta&msisdn=35700000000"
> GET /cy/stop?campaign_name=XXXX&api_key=XXXX&network=cyta&msisdn=35700000000 HTTP/1.1
> Host: client.txtnation.com
> User-Agent: curl/7.64.1
> Accept: */*
>
< HTTP/1.1 200 OK
< X-Served-By: Eos
< Content-type: text/html; charset=UTF-8
< Content-Length: 62
< Date: Wed, 18 Dec 2019 12:04:58 GMT
< Server: txtNation HTTP Server
<
{"success":true,"statusCode":0,"statusMessage":"Unsubscribed"}

Successful requests will be responded to with a JSON-formatted object containing a boolean status value of true.

{"success":true,"statusCode":0,"statusMessage":"Unsubscribed"}

Failed responses will contain a non-zero status code in the  statusCode parameter, with a relevant message in the statusMessage parameter. For your convenience, a list of potential status codes are provided in Status Codes.

Status codes

If your API submission was not successful, a non-zero status code will be returned in JSON format. As part of this object, there will be statusCode and statusMessage parameters which can be used to determine why the request failed. It will also be accompanied by a status parameter that is set to false.