Development

Three Easy Steps to Purchasing Phone Numbers Over API

Easily purchase and manage dedicated Virtual Long Numbers in 39 countries across the globe over Infobip API.

February 14 2017

The ability to purchase a mobile phone number over an API opens a whole new set of possibilities for your business communication. By adding just a lines of code, you can add number purchasing in your flow without ever leaving the comfort of your back-end.

Additionally, this solution is most useful to businesses who need a gapless way of offering our numbers to their customers without having to figure out various supply chain methodologies and put themselves at risk when they hold a multitude of numbers.

They cannot predict which customers will want numbers where, and the cost of holding these numbers in stock month-to-month creates a lot of financial risk, especially if they aren’t in the communications business.

Many times we see that SMS and Voice channels add value to certain platforms, but aren’t the main purpose or feature. These companies like to run lean operations, and are looking for vendors that can help them build powerful capabilities. Furthermore, this kind of partnerships results in automation, ensuring low overhead for managing many different customer requests and preferences.

All of this makes the Infobip platform an excellent choice for companies looking to extend 2-Way messaging capabilities to their business clients. From property management and quick integration with CRM systems for Marketing and customer support, to business-to-customer messaging like medical checkup reminders, allowing quick options of setting up and purchasing numbers without all the legwork, speeds up time-to-market, provides and instant value add in terms of services offered and offers far less congestion of internal processes.

First implemented over the Infobip Portal, now we’ve extended the number purchasing and managing option over API. And it’s a simple, 3-step process. So, let’s get started with 2-way messaging over the Infobip API.

The first step is to purchase the available numbers, then configure them according to different scenarios for receiving messages and, finally, set the right receiving method (pull or forward).

FIRST STEP: Purchasing the phone number for receiving messages

In order to start receiving messages from your users you will need a number which has the ability to receive messages, so you will have to purchase a number.

There are two types of purchased numbers that can be displayed:

  • Virtual Long Numbers (VLNs) – represents a standard looking phone number, which is usually the same as any other personal number (eg. 442312345678)
  • Short codes* – represent numbers with no country or network prefix, what gives them a more distinctive look than VLNs and makes them easily memorable (eg. 11485)

Both types have the best performance on a country level, so we suggest getting multiple numbers, if you need to operate in more than one country. Purchased numbers will allow you to receive incoming messages from your customers and, in some cases, you can use it as a sender’s ID (depending on the region you wish to use your number for).

NOTE: For purchasing of Short code numbers contact your Account Manager.

Except purchasing numbers, this phone number API lets you:

  • List available numbers:
GET /sms/1/numbers/available 

Response:


{
  "numbers": [
    {
      "numberKey": "78D8394AC3EG0460B4CF0E723FC31B49",
      "number": "79029555551",
      "country": "RU",
      "type": "VIRTUAL_LONG_NUMBER",
      "capabilities": [
        "SMS"
      ],
      "shared": false,
      "price": {
        "pricePerMonth": 15,
        "setupPrice": 0,
        "initialMonthPrice": 9.193549,
        "currency": "EUR"
      }
    },
	…
    ]
}
  • Purchase numbers using the number key of available numbers:
POST /sms/1/numbers
 
{
 "numberKey": "58B3840032C7774BAC840EEEA2C23A44"
}

Response:

{
  "numberKey": "6FED0BC540BFADD9B05ED7D89AAC22FA",
  "number": "447860041117",
  "country": "GB",
  "type": "VIRTUAL_LONG_NUMBER",
  "capabilities": [
    "SMS"
  ],
  "shared": false,
  "price": {
    "pricePerMonth": 5,
    "setupPrice": 0,
    "currency": "EUR"
  }
}

Additional methods for a complete number management experience are also available:

  • List all of your purchased numbers:
  • Get single purchased number by the number key:
  • Cancel your purchased number:

All of this steps will help you in managing your number(s) and after you’ve done that you are ready for the next step – for configuration.

SECOND STEP: Configuration container setup

Second step of this process is the configuration, that has to be created before the next step, which is action. It needs to be done, because the action can only exist inside of the configuration container.

You can configure every purchased number, depending on the scenario for receiving messages. Also, every number can have one or more configurations. When an SMS is received, the first word of the message is compared with the configuration keyword. If the keyword matches, actions will be executed as a message delivery method.

The process of configuration can be associated with a keyword, but it doesn’t have to be. When you choose a configuration without a keyword, it serves as “catch all” failure safe in case of receiving an SMS without a keyword:

POST /sms/1/numbers/78D8394AC5EG0460B4CF0E723FC31B49/configurations 

If you choose a configuration using a keyword you will have to add a keyword parameter:

POST /sms/1/numbers/78D8394AC5EG0460B4CF0E723FC31B49/configurations 
 
{
 "keyword": "INFOBIP"
}

Also, there are some additional options available for having a better overview of your configurations:

  • List all configurations:
GET /sms/1/numbers/78D8394AC5EG0460B4CF0E723FC31B49/configurations 
 
  • Get single configuration

To get a single configuration, you will have to use a configuration key:

GET /sms/1/numbers/78D8394AC5EG0460B4CF0E723FC31B49/configurations/54AD1CA328536A09AD1CA328536A09D8 
  • Update configuration

With this method you can update your keyword and validity period for a single configuration using the configuration key:

PUT /sms/1/numbers/78D8394AC5EG0460B4CF0E723FC31B49/configurations/54AD1CA328536A09AD1CA328536A09D8 
 
{
 "keyword": "API",
 "activeFrom": "2016-09-29T11:50:16.000+0000",
 "activeUntil": "2017-09-29T11:50:16.000+0000"
}
  • Delete configuration

To delete a configuration, you will have to use a configuration key:

DELETE /sms/1/numbers/78D8394AC5EG0460B4CF0E723FC31B49/configurations/54AD1CA328536A09AD1CA328536A09D8 

THIRD STEP: Setting up the delivery methods

When you purchase number(s), one of the steps you will need to take is setting up the delivery method. There are two possible solutions – pull method and forward method.

Pull API method

Using the pull method requires a simple API call that will return received messages:

GET /sms/1/inbox/reports 

Have in mind that all of the received messages can be pulled only once with this method. When a certain message gets pulled, it won’t be available for the next API call, which means that every time you make an API call, you will receive messages that arrived after the last API call was made – just the new messages.

Also, this method enables limiting the number of messages in one request by adding the limit parameter:

GET/sms/1/inbox/reports?limit=2

Pull method saves all of your received messages in Infobip message inbox. Messages will remain in the inbox until you decide to collect them by calling, already mentioned, pull API method.

HTTP forward method

As opposed to pull method, forward method will deliver messages to your number in real time. For receiving incoming forwarded messages, you will have to set up a URL on your web server that can receive POST request from our system.

When our system receives the mobile originated message, it will be forwarded to the URL that you must provide during the action setup. The message you receive from your customer is going to be located in our system:

{
 "results": [
   {
     "messageId": "817790313235066447",
     "from": "385916242493",
     "to": "385921004026",
     "text": "QUIZ Correct answer is Paris",
     "cleanText": "Correct answer is Paris",
     "keyword": "QUIZ",
     "receivedAt": "2016-10-06T09:28:39.220+0000",
     "smsCount": 1,
     "price": {
       "pricePerMessage": 0,
       "currency": "EUR"
     },
     "callbackData": "callbackData"
   }
 ],
 "messageCount": 1,
 "pendingMessageCount": 0
}

Exposing a web page and listening for HTTP request will get this method working. Every time your purchased number receives a new message, Infobip will initiate a HTTP request that contains that message.