Two-way SMS, send and receive SMS from anywhere in the world

Every message is an opportunity. Delight your customers with each one, every time


Quick start

Make sure you’ve read Getting Started.

About

SMS can be sent or received using the SMS API. Go ahead and experiment with the SMS API. This API is currently available in BETA, you need to apply for the production version. In your dashboard you can apply for the production SMS API after which KPN will follow up on your request.

Send SMS

You can send SMS using mobile number, content and sender parameters in the request body of the SMS API.

Receive SMS

SMS using this API is easy. In order to do so, you'll need to create a webhook endpoint. Then you should register it using the SMS API. After you have registered your webhook endpoint/callback URL you can send an SMS using the mobile number, content, and sender parameters in the request body and selecting the yes option in the ‘inbound’ header of the SMS API. Inbound messages sent by SMS recipient will be delivered to this registered webhook.

 

How it works

To get started and test the API from your local workstation you can use Postman or our API Reference (powered by SwaggerHub) or cURL as an HTTP client. If you use the Postman collection or API Reference, make sure you update the environment settings with your credentials in order to authenticate.

 

 

If you use cURL scroll down to see the examples.

 

Connect to the API

To start testing the API you need to get authorization credentials. Log in to your account and create a developer app on the My Apps page. The steps to create a developer app are briefly discussed under 'Support' 🡆 'Frequently Asked Questions'.

Get access token

Copy your app's credentials and replace APP_CONSUMER_KEY and APP_CONSUMER_SECRET with the copied values, then execute the below cURL command to receive an access token.

You can use same token to make multiple 'API' calls, provided the token is active. If the token expires then you can repeat this step.


curl -X POST \
 'https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials' \
 -H 'content-type: application/x-www-form-urlencoded' \
 -d 'client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET'

The authorization service returns a JSON message that contains the access token field.

{
    "refresh_token_expires_in": "0",
    "api_product_list": "[SMS - Nexmo]",
    "api_product_list_json": [
        "SMS - Nexmo"
    ],
    "organization_name": "kpn",
    "developer.email": "demo123@kpn.com",
    "token_type": "BearerToken",
    "issued_at": "1521039195424",
    "client_id": "2Xvp2YLhEeT8w4cXQWvKuOpMoHQQ9zGx",
    "access_token": "haf2SDl07E9N7RluNQ4kJ1TkGgso",
    "application_name": "6e38ed2d-48b1-4362-97d6-04254065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

Send SMS

Copy your access_token and replace access_token with the copied value, then you can execute the below cURL command to send a SMS.


curl -X POST \
  'https://api-prd.kpn.com/communication/nexmo/sms/send' \
  -H 'authorization: Bearer access_token' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'from=DemoApp&to=3162*******&text=Hello'

Receiving an SMS

Handling inbound SMS with with the API is easy. You just need to create a webhook endpoint and configure your number or account to point to the endpoint. If you are a test user then you can try inbound messaging using below using 'Register Webhook endpoint'. Otherwise, you should use the Phone Numbers API to search, buy and manage your virtual number. In order to use the Phone Numbers API you should request access as a premium user.

Register Webhook endpoint

As a test user you can try inbound messaging by registering your webhook against your own phone number you use for testing, without buying a virtual number. This is not applicable if you are a premium user.

curl -X POST \
  'https://api-prd.kpn.com/communication/nexmo/sms/register' \
  -H 'authorization: Bearer access_token' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'to=3162*******&callback_url=https://example.com:webhooks/inbound-sms'

If you are a premium user then you should manage your numbers using the Phone Numbers API. Under 'Update a number' you can register your webhook against your virtual number using the 'moHttpUrl' parameter


curl -X POST \
  'https://api-prd.kpn.com/communication/nexmo/phone-numbers/number/update' \
  -H 'authorization: Bearer access_token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'country=NL&msisdn=447700900000&moHttpUrl=https://example.com:webhooks/inbound-sms'

Send and Receive SMS

Copy your access_token and replace access_token with the copied value, then you can execute the below cURL command to send SMS. If you are a test user then VirtualNumber will be your own number that you registered with your webhook. When you reply to the number then you will see the response in your webhook.

curl -X POST \
  'https://api-prd.kpn.com/communication/nexmo/sms/send' \
  -H 'authorization: Bearer access_token' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'from={VirtualNumber}&to=3162*******&text=Hello'