Inbound SMSs are another way of connecting with your recipients. They allow recipients to send SMSs back to you, perhaps to request extra information, enter a competition, or change the settings of their account.
If you'd like to handle inbound text messages, you need to register a keyword. A keyword is unique to your instance which means that they aren't shared between Staging and Production environments.
When an inbound message is received, the phone number from which it originates is matched against an existing recipient within your instance. You may also choose to allow the creation of new recipients when receiving an inbound message from a previously unknown phone number. This setting is found in the Settings module in the subsection 'Mobile'. If this setting is enabled and the recipient does not already exist, Agillic creates a new recipient.
If you want to use this feature, it's required that you index the Person Data field that holds values for mobile numbers. This is important in order to ensure that messages have a high enough performance to make sure all messages actually reach Agillic. Read more about how to apply an index to a Person Data field here.
In this article, you'll find information about:
The Basics of Setting Up Inbound SMS
Keywords
The Product Specialists in Agillic Support or your Customer Success Manager will be able to assist you in registering a keyword with the default SMS Gateway provider. There are no limits to the number of keywords you can set up, as long as they are available at the service provider.
Please note that these keywords have an associated monthly cost, the cost listed on your price list.
It often makes sense to register the name of the instance as a keyword. This allows you to reuse the keyword in different contexts.
Shortcode
When sending an inbound SMS, you send the SMS to a Shortcode.
Agillic's default gateway for Danish inbound SMS keywords is the shortcode 1980. You will receive the gateway shortcode for your country when you order your first keyword.
Shortcodes in Different Countries
Shortcodes are country-specific. For example, the Danish shortcode is 1980 and the shortcode for the United Kingdom is 88440.
Shortcodes follow the country in which the user's subscription/sim plan belongs, not the country where the user is geographically located. This means that users travelling abroad will be reachable via your normal SMS Flow and shortcodes.
As an example, a Danish mobile can send an inbound SMS and trigger actions using a Danish shortcode, even if the user is currently on vacation in Sweden. However, they will not be able to trigger inbound actions using a Swedish shortcode due to their mobile being Danish.
How to Configure Inbound SMS
Once you've registered a keyword, you may now begin configuring the Inbound SMS settings. Inbound text messages may be used to either trigger Events or update Person Data values. The Inbound text message will always have to start with the keyword.
Contact your Customer Success Manager or the Product Specialists in Agillic Support to reserve your keywords. After the keywords are registered, you can configure Agillic to understand inbound SMS from your users by defining the syntax.
Inbound SMS settings
Syntax
The Syntax determines how the inbound message is interpreted in terms of which Events and Person Data fields to update with the received content.
In this example, we've registered the keyword ‘AGCANDY’ at 1980, and configured the following syntax in ‘Inbound SMS’ settings:
AGCANDY PERMISSION
‘PERMISSION’ here is the name of a Person Data field. This would allow a recipient to send in the following message: ‘AGCANDY yes’ which would result in the value ‘yes’ being saved to the person data field ‘PERMISSION’.
The syntax for updating Person Data is, therefore as follows. Please replace the placeholder text with the relevant values.
Syntax - {KEYWORD} {NAME OF PERSON DATA}
Example - AGCANDY yes
You have to register an additional keyword for each syntax you wish to support.
Inbound SMS Syntax Examples
SMS syntax is used to set up inbound SMSs in Agillic. You can set up the syntax in the Settings module which allows Agillic to trigger Events and change Person Data.
The examples below of inbound SMS syntax use 'Candy' as the keyword.
Person Data Examples:
| Syntax | Example of SMS | Change in Agillic |
| Candy SATISFACTION | Candy 5 | The Person data SATISFACTION is set to '5' |
| Candy EMAIL PERMISSION | Candy me@agilliccandy.com yes | The Person data EMAIL is set to 'me@agilliccandy.com' and PERMISSION is set to 'yes' |
| Candy FULL_NAME | Candy Hans Christian Andersen | The Person data FULL_NAME is set to 'Hans Christian Andersen' |
| Candy FULL_NAME SATISFACTION | Candy Hans Christian Andersen 5 | The Person data FULL_NAME is set to 'Hans' and SATISFACTION is set to 'Christian Andersen 5' |
| Candy SATISFACTION FULL_NAME | Candy 5 Hans Christian Andersen | The Person data SATISFACTION is set to '5' and FULL_NAME is set to 'Hans Christian Andersen' |
Event Examples:
The following is for Events with no spaces.
| Syntax | Example of SMS | Change in Agillic |
| {blank} | Candy signup | Activates the event 'candy' and the event 'signup', if available |
Always write Events in lowercase and make sure that the Events already exists in Agillic. If an inbound SMS contains a word like 'Signup', Agillic will first attempt to trigger the 'Signup' Event. If the Event isn't found, Agillic tries again with all lowercase - 'signup' Events.
The following is for Events with spaces. You can use double quotes to specify an Event with spaces in the name.
| Syntax | Example of SMS | Change in Agillic |
| Candy "email signup" | Candy email signup | Activates the Event "candy" and the Event "email signup", if available |
Person Data and Events Examples:
| Syntax | Example of SMS | Change in Agillic |
| Candy * EMAIL | Candy signup me@agilliccandy.com |
The Event 'signup' triggers and the Person data EMAIL is set to 'me@agilliccandy.com' |
As some Person Data, such as FIRSTNAME, may have values with spaces, we recommend placing Person Data at the end of a syntax. This avoids confusion where a first name, like 'Mary Ann', would save 'Mary' as FIRSTNAME and attempt to trigger an Event called 'Ann'.
Also, Agillic will recognise any value with an '@' as an email address and save it as the email address of the user. This can be more secure than using "EMAIL" in syntax as it would not allow invalid email addresses to save.
How to Set the Syntax for Inbound SMS
- Open the Settings module.
- Locate the 'System Settings' section.
- Open the 'Mobile' subsection.
- Fill in the syntaxes that you want to use in the 'Keywords' field. Separate multiple syntaxes with a semicolon.
- Click 'Save'.
Inbound SMS set up with a syntax that allows recipients to send in the keyword 'Candy' and a number ( such as from 1-10) which will save in the SATISFACTION Person Data Field.
Testing Inbound SMS
You can test your Inbound SMS configuration in two ways:
- By sending an actual SMS to your registered shortcode and keyword.
- By testing the configuration on Staging by an HTTP call.
Testing by Sending an Inbound SMS
- Send an SMS with supported syntax.
- Log into the Staging environment.
- Check your recipient's Person Data or investigate the recipient if an Event should trigger.
- Verify that the Event and/or Person Data has triggered/changed as intended.
Testing by doing an HTTP call
In the example below, replace the placeholders:
- {PLACEHOLDER1} is replaced to match the name of your instance.
- {PLACEHOLDER2} is replaced to match the phone number you wish to simulate a message from.
- {PLACEHOLDER3} is replaced to match the message you wish to send.
Link - https://{PLACEHOLDER1}-stag.agillic.eu/inboundsms/IPXInbound?OriginatorAddress={PLACEHOLDER2}&Message={PLACEHOLDER3}
When replacing the placeholders, the link would look like the following example:
Example - https://agilliccandy-stag.agillic.eu/inboundsms/IPXInbound?OriginatorAddress=4501234567&Message=AGCANDY stop
You can test this by visiting the completed URL in a browser, or by performing an HTTP POST call using a tool of your choosing such as cURL or Python.
Suggested Next Steps