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.

HTTP

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:

JSON

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

HTTP forward example:

JSON

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

Response:

JSON

{
  "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.

HTTP

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

Example response:

JSON

{
	"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

JSON

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

Response:

JSON

{
  "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

HTTP

PUT /numbers/2/numbers/{numberKey}/sms

JSON

{
	"key": "8F0792F86035A9F4290821F1EE6BC06A",
	"keyword": "NEWKW_UPDATE",
	"action": {
		"type": "MAIL_FORWARD",
		"mail": "update@update-something.com"
	}
}

Delete a configuration

This method will delete the configuration.

HTTP

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

Response: A successful response is presented by the HTTP status code 204 No Content. There is no response body.

Voice

HOW TO USE VOICE ACTIONS

Every Voice-enabled number can have one configuration action which defines how do we handle the incoming call received on this Voice number.

We support the following action configuration over API:

         - 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 should be used if you want your incoming calls to be answered by a predefined IVR scenario. You need to create an IVR scenario first and you could do that using API or our portal.

Number masking

Number masking enables you to use dynamic call forwarding of the incoming call to another phone number depending on the response value we received from your platform. For each incoming call we receive on the Number masking configured Voice number, our platform sends the request to your platform and expects a response with the phone number to forward the call to. You may also provide us with a caller ID to be presented on the receiving side.

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.

HTTP

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

Response:

JSON

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

Create voice setup on a number

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

HTTP

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

JSON

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

Example creating NUMBER_MASKING action:

JSON

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

Update voice setup on a number

This method updates voice setup previously created on a number

HTTP

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

Example:

JSON

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

Delete voice setup on a number

This method removes voice setup from

HTTP

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

This is new Numbers Configuration documentation!

To access the old documentation, please visit this link.