Getting started with Powerpack

Sending SMS messages using regular 10-digit phone numbers (a.k.a long codes) is heavily regulated in the US and Canada. Long codes, however, remain the medium of choice for businesses seeking to engage with their customers via SMS. The personalized touch long codes lend to a conversation, their price advantage, and the easy procurement process makes long codes a natural choice for most use cases.

Powerpack makes SMS communication using long codes effective and reliable at scale. It is designed to meet your overall SMS throughput and volume requirements, regardless of scale.

By automatically distributing your overall SMS traffic across a pool of source numbers, Powerpack keeps you compliant with per day and per second throughput limits defined by the CTIA (Cellular Telecommunications Industry Association).

Powerpack Features

  • Number pool - Powerpack intelligently distributes your outbound SMS traffic over a pool of source numbers optimal for your overall SMS volumes. Setting up a pool of source numbers that is just right for your SMS volumes only takes a few seconds.
  • Sticky Sender - If your use case requires you to contact the same subscriber more than once, Sticky Sender helps maintain a single thread of conversation by always sending messages to the subscriber from the same source number in the pool.
  • Local Connect - Keeping with the theme of making SMS communication personal, Local Connect helps prioritize phone numbers in the pool which belong to the region and/or area code of the subscriber.
  • Prioritize Shortcodes - If you have Shortcodes added to your Powerpack, “Prioritize Shortcodes” feature configures the Powerpack to resolve Shortcodes as source over other numbers while sending outbound messages. In cases where the destination country or the destination mobile network is not supported by the Shortcode, other numbers in your Powerpack will be used.

Local Connect

Local Connect is designed to make SMS communication personal. It ensures that SMS messages get sent via a local phone number of the same area code or region as the destination number.

Enabling Local Connect

Local Connect preferences can be managed from the Powerpack management console.

Enable Local Connect

Local Connect preferences can be updated for existing Powerpacks at anytime. Any update to your Local Connect preference will reflect in the source number resolution logic instantaneously.

Sticky Sender

Sticky Sender is designed to maintain a single thread of conversation. It ensures that SMS messages are sent to the subscriber from the same source number in the pool.

Enabling Sticky Sender

Sticky Sender preferences can be managed from the Powerpack management console.

Enable Sticky Sender

Sticky Sender preferences can be updated for existing Powerpacks at anytime. Any update to your Sticky Sender preference will reflect in the source number resolution logic instantaneously.

How Region Based Source Number Resolution Works

Flowchart

For Example –

If you’re sending an SMS message to a San Francisco number beginning with 415:

  • If a phone number with prefix 415 is present in the Number pool, Powerpack will use it to send the outbound SMS

  • If a phone number with 415 prefix is not found in the number pool, or if all the phone numbers with 415 prefix in the pool have already been used to recommended capacity (150 messages/day), Powerpack will deliver the SMS through any other phone number of the same region as the destination number (California in this case).

  • If no phone numbers of the same region are found in the Powerpack, the SMS would be sent via a random US phone number.

  • If no US phone numbers are found in the pool, the SMS would be sent via a Canada number.

Add Shortcodes to Powerpack

You can now add Plivo Shortcodes to existing or new Powerpacks. With the ability to add Shortcode numbers to your Powerpack, you can combine the benefits of Shortcodes and Powerpack.

Shortcodes are the product of choice when it comes to high scale and delivery rates. Combining them with Powerpack, enables you to:

  • Run multi-region SMS campaigns.Shortcode numbers are country specific and can only send messages to countries they were provisioned for. While sending messages to multiple countries, Powerpack will fallback to using other numbers in your Number pool if the Shortcode belonging to the destination country is not added to the Powerpack, providing you a seamless flow of outbound messages.

    For Example: If you have added a US Shortcode in your Powerpack and want to run a campaign spanning the US and Canada, Powerpack will use the US Shortcode for your US traffic and will fallback to other numbers in the Pool for the Canada traffic.

  • Reach networks not supported by your Shortcode. Even though Shortcodes have reachability to most of the destination mobile networks, there might be some networks which are not supported. In such cases, Powerpack intelligently fallbacks to using other number in the Pool.

    For Example: If you are sending messages to destination networks C1 and C2 using Powerpack and C2 is not supported by the configured Shortcode. Powerpack will use the other numbers in the pool for sending messages to C2 mobile network and Shortcode for C1.

To use Shortcodes with Powerpack:

  • Contact Support to add Shortcode to your Powerpack. You will have to provide the name of the Powerpack you want to add the Shortcode to.You can add multiple Shortcodes to the same Powerpack, one each for the US and Canada.
  • Once you have the Shortcode added to your Powerpack,you can use “Prioritize Shortcode” feature in Powerpack to manage the use of Shortcodes through Powerpack.
    • Enabled : Shortcode will be used to send the outbound message if the destination network and country is supported by the Shortcode. Else, Powerpack will fallback to using other numbers in the number Pool.
    • Disabled: Shortcodes will not be used to send outbound messages. Instead, other numbers in number pool will be used as source for all outbound messages from that Powerpack.

Add ShortCode Powerpack

Receive Incoming Messages

Handle all incoming messages to the Powerpack phone numbers using Plivo Applications. To create a new Plivo Application navigate to the create new Application section on your Plivo console. Once created, you can associate this application to your Powerpack.

Once you have configured an Application for your powerpack, all incoming messages to your Powerpack phone numbers are posted to the message_url in your Plivo Application.

Creating a New Powerpack

To create a new powerpack

  1. Login to your Plivo Console dashboard.
  2. Navigate to the SMS Powerpack management console. SMS Powerpack

  3. On the SMS Powerpacks page, click Add New Powerpack. New Powerpack

  4. In the Properties section, enter a name for the new Powerpack.
  5. Enable Sticky Sender if you would like to ensure that messages to a particular destination number are always sent from the same Powerpack source number.
  6. Enable Local Connect if you would like to ensure that Powerpack prioritzes source number belonging to same region or area code as the destination number for an outbound SMS.
  7. In the application settings, select the application type and name from the respective dropdowns.
  8. In the Configure Number Pool section, enter the count of phone numbers at a country and/or region level.
    • To configure your Number Pool at a country level: Enter your daily SMS volume for US and Canada. Plivo will recommend the optimal phone number pool size based on your input.

    Country Composition

    • To configure your Number Pool at an area code or region level: Use the Advanced settings option to add Phone numbers to the Number Pool at a more granular level as shown below.

    Composition

    Pro Tip:

    If you don't need to get more granular than state level region matching, simply specify the total count of numbers against any one prefix of that State.

  9. Specify the Pool Size, and click Add Powerpack. This will initiate the purchasing and provisioning of phone numbers.

Sending Outbound Messages

To send messages using Powerpack

  1. On the SMS Powerpack page, click All Powerpacks to view all of your Powerpacks.
  2. Copy the Powerpack ID for the powerpack you wish to use. SMS Powerpacks

  3. Enter your Powerpack ID for powerpack_uuid in the Send SMS API request.

Code Samples

1
2
3
4
5
6
7
8
import plivo

client = plivo.RestClient('AUTH_ID','AUTH_TOKEN')
message_created = client.messages.create(
    powerpack_uuid='your_powerpack_uuid',
    dst='destination_number',
    text='Test Message'
)
1
2
3
4
5
6
7
8
9
10
11
12
13
require 'rubygems'	
require 'plivo'	

include Plivo	

client = RestClient.new("AUTH_ID","AUTH_TOKEN")
response = client.messages.create(	
  nil,	
  [destination_number],	
  'Test Message',	
  powerpack_uuid: 'your_powerpack_uuid'	
)	
puts response
1
2
3
4
5
6
7
8
9
10
11
12
let plivo = require('plivo');
let client = new plivo.Client('AUTH_ID','AUTH_TOKEN');

client.messages.create(
  null,
  'destination_number',
  'Test Message',
  {},
  'your_powerpack_uuid'
).then(function (message_created) {
  console.log(message_created)
})
1
2
3
4
5
6
7
8
9
10
11
require 'vendor/autoload.php';	
use Plivo\RestClient;	

$client = new RestClient('AUTH_ID', 'AUTH_TOKEN');	
$message_created = $client->messages->create(	
    null,	
    ['destination_number'],	
    'Test Message',	
    [],	
    'your_powerpack_uuid'	
);	
1
2
3
4
5
6
7
8
9
10
11
12
13
package com.plivo.api;

import com.plivo.api.models.message.Message;
import com.plivo.api.exceptions.PlivoRestException;
import java.io.IOException;
import java.util.Collections;

class Example {
  public static void main(String[] args) throws IOException, PlivoRestException {
    Plivo.init("AUTH_ID", "AUTH_TOKEN");
    Message.creator(Collections.singletonList("destination_number"), "Test Message", "your_powerpack_uuid").create();
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
package main

import "github.com/plivo/plivo-go"

func main() {
	client, err := plivo.NewClient("AUTH_ID", "AUTH_TOKEN", &plivo.ClientOptions{})
	if err != nil {
		panic(err)
	}
	client.Messages.Create(plivo.MessageCreateParams{
		PowerpackUUID: "your_powerpack_uuid",
		Dst:           "destination_number",
		Text:          "Test Message",
	})
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
using System;	
using System.Collections.Generic;	
using Plivo;	

internal class Program	
{	
    public static void Main(string[] args)	
    {	
        var api = new PlivoApi("AUTH_ID", "AUTH_TOKEN");	
        var response = api.Message.Create(	
            powerpack_uuid:"your_powerpack_uuid",	
            dst:new List<String>{"destination_number"},	
            text:"Test Message"	
        );	
        Console.WriteLine(response);	
    }	
}	

Updating a Powerpack

To modify or update your Powerpack

  1. On the SMS Powerpacks page, click All Powerpacks to view all of your Powerpacks.
  2. Select the Powerpack you wish to modify or update.
  3. In the Properties section, modify Sticky Sender by enabling or disabling it, and then click Update.

  4. In the Properties section, modify Local Connect by enabling or disabling it, and then click Update.

Update Properties

  1. In the application settings, modify the application by selecting the type and name from the respective dropdowns.

  2. In the Number Pool Composition section, total count of phone numbers in the Number Pool are displayed for each country.
    • To update your Number Pool composition at a country level: Update the number count for the country and click on Update

    Update Composition Country

    • To update your Number Pool composition at an area code or region level: Open Advanced settings and update the number count for the region or area code and click on Update

    Update Composition Region

    • If you are increasing the pool size, a dialogue box will prompt you to confirm the purchase of new numbers.
  3. You can also manually remove phone numbers from your number pool by clicking on View Numbers. Numbers Pool

  4. Select Delete & Unrent against the number you wish to remove from your number pool.