Create subscription

Creating subscriptions sample code

The PHP code snippet below shows how to add a number to a subscription service.

The code uses our PHP SDK

<?php
require 'vendor/autoload.php';
use AfricasTalking\SDK\AfricasTalking;

// Set your app credentials
$username = "MyAppUsername";
$apikey   = "MyAppAPIKey";

// Initialize the SDK
$AT       = new AfricasTalking($username, $apiKey);

// Get the sms service
$sms      = $AT->sms();

// Get the token service
$token    = $AT->token();

// Set your premium product shortCode and keyword
$shortCode   = 'myPremiumShortCode';
$keyword     = 'myPremiumKeyword';

// Set the phone number you're subscribing
$phoneNumber = "+254711XXXYYY";

try {
    // Get a checkoutToken for the phone number you're subscribing
    $checkoutTokenResult = $token->createCheckoutToken([
        'phoneNumber'    => phoneNumber
    ]);

    $checkoutToken       = $checkoutTokenResult->token;

    // Create the subscription
    $result = $sms->createSubscription([
        'shortCode'      => $shortCode,
        'keyword'        => $keyword,
        'phoneNumber'    => $phoneNumber,
        'checkoutToken'  => $checkoutToken
    ]);

    print_r($result);
} catch (Exception $e) {
    echo "Error: ".$e->getMessage();
}

Two endpoints are required in order for your application to complete a premium sms subscription request. These are:

  • Checkout Token request: The checkoutToken is used to authorize a premium sms subscription. It is required in order to subscribe a phone number.
  • Subscription request: Once a checkoutToken is received it should be sent along with the rest of the parameters to initiate the actual subscription request.

Generate a checkout token

Generate a checkoutToken by making a HTTP POST request to the following endpoints:

Endpoints

Live: https://api.africastalking.com/checkout/token/create
Sandbox: https://api.sandbox.africastalking.com/checkout/token/create

The following headers are required:

Parameter Description
Content-Type
String
The requests content type. Must be application/x-www-form-urlencoded

Request Parameters

Parameter Description
phoneNumber
String
Required
The phone number you want to create a subscription for

Open Endpoint

This is an open endpoint and does not need your authentication credentials.

Checkout token response

The body of the response will be a JSON object containing the following fields:

Parameter Description
description
String
A description of the status of the request. Possible values are:
  • Success
  • Failed
token
String
The checkout token to be used
{
    "description": "Success",
    "token": "CkTkn_SampleCkTknId123"
}

This token shall be expected later when initiating the actual create subscription request.

The tokens expire after 10 minutes and are limited to 2 tokens for a 5 minute window for each source IP Address.

Subscribe a phone number

You can subscribe a phone number by making a HTTP POST request to the following endpoints:

Endpoints

Live: https://api.africastalking.com/version1/subscription/create
Sandbox: https://api.sandbox.africastalking.com/version1/subscription/create

Request Parameters

In addition to the standard request headers, the body of the request should contain the following fields:

Parameter Description
username
String
Required
Africa's Talking application username.
shortCode
String
Required
This is the premium short code mapped to your account.
keyword
String
Required
This is the premium keyword under the above short code mapped to your account.
phoneNumber
String
Required
The phoneNumber to be subscribed.
checkoutToken
String
Required
This is a token used to validate the subscription request.

API Response

The body of the response will contain the following fields:

Parameter Description
status
String
Indicates whether the prompt to subscribe to this shortcode was successfully raised or not. Possible values are:
  • Success
  • Failed
Description
String
Describes the status of this subscription request.

Below is a sample premium sms subscription response for a successful request:

{
    "status": "Success",
    "description": "Waiting for user input"
}