Number configuration

Besides sending SMS messages, our platform fully supports the reception of incoming SMS messages and Voice calls from your users. Configuration and Action setup will enable you to achieve that.
 

HOW TO RECEIVE INCOMING SMS?

Setup for receiving incoming SMS messages is a two-step process, assuming you have already purchased a phone number. - Configuration setup - Action setup

During the Action Setup, you can decide about the method of receiving messages: - Pull method - HTTP forward method

The configuration is a logical container for Actions. You can choose the method of incoming message delivery through the Action setup, but before you do that, a Configuration must be created since the Action can only exist inside the Configuration container.

Action is a container for setting up the way how to process the incoming message. There are two types of actions that can be performed:

Pull method allows you to fetch new messages from the Infobip server over API at your convenience

HTTP forward method allows you to receive messages from your subscribers in real-time

           -- HTTP POST - Receive messages via POST request in the request body
           -- HTTP GET - Receive messages via GET request as part of the URL query string

Configuration with the keyword

Each phone number can have one or many Configuration containers. A Configuration container may be assigned a keyword. Only one container without a keyword is allowed, and all others must have unique keywords.

When an SMS is received on this phone number, the first word of the message will be compared with the Configuration keywords, and if there is a match, the Action rule of the matched container will be executed as message delivery method (Pull or Forward).

CONFIGURATION WITHOUT KEYWORD

Besides Configurations with keywords, we recommend you always have a Configuration that is not keyword-enabled to serve as a “catch-all” fail-safe in cases where SMS without keywords are received.

These messages will be stored in the Message Log accessible on Portal or using API (more details)

SMS

Available methods

  • Create a new configuration
  • List all configurations
  • Get a single configuration
  • Update a configuration
  • Delete a configuration

Configuration mode

Property name Type Description
configurations object An object containing configuration details
configurations.key string Unique ID of the Configuration.
configurations.keyword string Keyword expected in a received message.
configurations.action object Object containing action details
configurations.action.type string Action model of receiving the messages. Must be __HTTP_FORWARD__, __MAIL_FORWARD__, __SMPP_FORWARD__, __PULL__.
configurations.action.url string A parameter used for HTTP_FORWARD action specifying URL to which new messages will be forwarded.
configurations.action.httpMethod string A parameter used for HTTP_FORWARD. The HTTP method used for forwarding. Must be __POST__ or __GET__.
configurations.action.contentType string A parameter used for HTTP_FORWARD when using the POST method. The format in which the content will be wrapped and sent in the request. Must be __JSON__ or __XML__.
configurations.action.mail string A parameter used for MAIL_FORWARD. Specify email adress(es) where to forward a message to.
otherActions string Other non-forwarding actions setup on the number. It can be AUTORESPONSE, BLOCK, UNBLOCK. These actions can be set
totalCount number A number of configurations setup on a number.

Create a new configuration

This method will create a new configuration for the number.

POST /numbers/2/numbers/{numberKey}/sms	
  

Parameters vary depending on the action. Forward to SMPP and PULL actions need only *keyword* and don't contain action object.

Email forward example:

{
	"keyword": "NEWKW",
	"action": {
		"type": "MAIL_FORWARD",
		"mail": "someone@something.com"
	}
}	
  

HTTP forward example:

{
  "keyword": "KEYWORD1",
  "action": {
    "type": "HTTP_FORWARD",
    "url": "http://something.com",
    "httpMethod": "POST",
    "contentType": "JSON"
  },
  "otherActions": {}
}	
  

Response:

{
  "key": "E9FCDCA496035F08EEA5933702EDF745",
  "keyword": "KEYWORD",
  "action": {
    "url": "http://something.com",
    "httpMethod": "POST",
    "contentType": "JSON",
    "type": "HTTP_FORWARD"
  },
  "useConversation": {
    "enabled": true
  },
  "otherActions": []
}	
  

List all configurations

This method returns all the configurations set up for a number.

GET /numbers/2/numbers/{numberKey}/sms	
  

Example response:

{
	"configurations": [{
		"key": "6336C2CCF10E74B705340E70D8E06BD6",
		"keyword": "KEYWORD1",
		"action": {
			"type": "HTTP_FORWARD",
			"url": "http://something.com"
		},
		"otherActions": ["AUTORESPONSE"]
	}, {
		"key": "8F0792F86035A9F4290821F1EE6BC06A",
		"keyword": "KEYWORD2",
		"action": {
			"type": "MAIL_FORWARD",
			"mail": "someone@something.com"

		},
		"otherActions": ["BLOCK"]
	}],
	"totalCount": 2
}	
  

Get a single configuration

This method fetches configuration details

GET /numbers/2/numbers/{numberKey}/sms/{configurationKey}	
  

Response:

{
  "key": "E9FCDCA496035F08EEA5933702EDF745",
  "keyword": "KEYWORD",
  "action": {
    "url": "http://something.com",
    "httpMethod": "POST",
    "contentType": "JSON",
    "type": "HTTP_FORWARD"
  },
  "useConversation": {
    "enabled": true
  },
  "otherActions": []
}	
  

Update a configuration

This method will update the configuration details. Parameters used vary depending on the action type, the same as with Create confi

PUT /numbers/2/numbers/{numberKey}/sms	
  
{
	"key": "8F0792F86035A9F4290821F1EE6BC06A",
	"keyword": "NEWKW_UPDATE",
	"action": {
		"type": "MAIL_FORWARD",
		"mail": "update@update-something.com"
	}
}	
  

Delete a configuration

This method will delete the configuration.

DELETE /numbers/2/numbers/{numberKey}/sms/{configurationKey}	
  

Response:

Voice

HOW TO USE VOICE ACTIONS

Every Voice-enabled number can have one action which will define what happens after we receive a Voice call.

Actions can be: - Forward to IVR - Number masking

VOICE API

Please notice that configurations and their configuration keys are available in Voice API which is documented here: - Number masking: https://dev.infobip.com/number-masking-for-voice-calls - IVR: https://dev.infobip.com/ivr

Forward to IVR

Forward to IVR action is used when you want to receive incoming calls to the IVR (Interactive Voice Response). Before using this action IVR needs to be created on Infobip platform, via API (documentation is available on https://dev.infobip.com/ivr). When the scenario is created it can be assigned to the number.

Number masking

Once the call is received on Voice (DID) number, Infobip’s call forwarding service enables forwarding calls to another destination / phone number which is dynamically selected. Infobip’s voice service enables masking of the caller ID, meaning that the caller ID on the end user’s side would not be the caller ID of the originator of the call, but some voice number (DID) from our operators range.

Available methods

  • Get voice setup on a number
  • Create voice setup on a number
  • Update voice setup on a number
  • Delete voice setup on a number

Voice configuration model

Property name Type Description
action

object

Action object encapsulating action type and parameters for the action.
action.type string Action type can be:
__FORWARD_TO_IVR__ for setting up inbound IVR scenario on the number,
__VOICE_NUMBER_MASKING__ for setting up Number Masking on the number.
Depending on the type different parameters are used for configuration.
action.scenarioKey string Used with __FORWARD_TO_IVR__. Scenario ID which identifies IVR scenario defined in our system. Used for setting up inbound IVR on the number.
action.voiceNumberMaskingConfigKey string Used with __VOICE_NUMBER_MASKING__. Configuration key of Number masking set up on Infobip platform.

Get voice setup on a number

This method will return voice setup on a number.

GET /numbers/2/numbers/{numberKey}/voice	
  

Response:

{
	"action": {
		"type": "FORWARD_TO_IVR",
		"scenarioKey": "56FE9214E7A98F2D4CB44E647E3D3CED"
	}
}	
  

Create voice setup on a number

This method will create a new voice setup on a number.

POST /numbers/2/numbers/{numberKey}/voice	
  

Parameters in “action” object depend on action type: VOICE_IVR uses scenarioKey parameter VOICE_NUMBER_MASKING uses callbackUrl and statusUrl

Example creating FORWARD_TO_IVR actio

{
	"action": {
		"type": "FORWARD_TO_IVR",
		"scenarioKey": "56FE9214E7A98F2D4CB44E647E3D3CED"
	}
}	
  

Example creating NUMBER_MASKING action:

{
	"action": {
		"type": "VOICE_NUMBER_MASKING",
		"voiceNumberMaskingConfigKey": "6336C2CCF10E74B705340E70D8E06BD6"
	}
}	
  

Update voice setup on a number

This method updates voice setup previously created on a number

PUT /numbers/2/numbers/{numberKey}/voice	
  

Example:

{
	"action": {
		"type": "FORWARD_TO_IVR",
		"scenarioKey": "A665D45B75EF7C54A9FFF99BF600603F"
	}
}	
  

Delete voice setup on a number

This method removes voice setup from

DELETE /numbers/2/numbers/{numberKey}/voice	
  

This is new Numbers Configuration documentation!

To access the old documentation, please visit this link.