{"__v":1,"_id":"57f61a01871979220010207e","category":{"__v":3,"_id":"5515472ac28d6125001b8884","pages":["551924db45b0d80d00152254","55194fec71a8cc210031db15","551e55590a72c50d0085b911"],"project":"54eb50e5615ffc1900305a16","version":"54eb63b859b1172100334fae","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-03-27T12:03:54.990Z","from_sync":false,"order":2,"slug":"receive-sms","title":"Receive SMS"},"parentDoc":null,"project":"54eb50e5615ffc1900305a16","user":"54eb4fdedf7add210007b29b","version":{"__v":18,"_id":"54eb63b859b1172100334fae","forked_from":"54eb63a1867e1917009b711d","project":"54eb50e5615ffc1900305a16","createdAt":"2015-02-23T17:30:32.501Z","releaseDate":"2015-02-23T17:30:32.501Z","categories":["54eb63b959b1172100334faf","54eb63b959b1172100334fb0","54eb63b959b1172100334fb1","54eb63b959b1172100334fb2","54ed8dd4ab373e2300f50eae","54ed99b2ab373e2300f50ede","55153a6de68daa2f00cff838","551546edbc466623002afe72","5515472ac28d6125001b8884","55154749c28d6125001b8885","555d9b4106dfec0d00d38ea7","5613e06e433e5735007c7708","5624bbb785a31117001c5403","56669e857cc81e0d00253f8e","568b8d837a42220d00498311","56a632277ef6620d00e2f18a","56d8147c3eb4dd0b00201aac","57a9ce2fac6db30e000d7efd","57a9cf4e944ea60e00dc3f74","58172386715dce0f00da4aa0","582dc59ee1b8692300c0dd03"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-10-06T09:31:45.831Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"name":"","code":"{  \n   \"results\":[  \n      {  \n         \"messageId\":\"ff4804ef-6ab6-4abd-984d-ab3b1387e823\",\n         \"from\":\"38598111\",\n         \"to\":\"41793026727\",\n         \"text\":\"KEY Test message\",\n         \"cleanText\":\"Test message\",\n         \"keyword\":\"KEY\",\n         \"receivedAt\":\"2015-02-15T11:43:20.254+0100\",\n         \"smsCount\":1\n      }\n   ]\n}","language":"json","status":200}]},"examples":{"codes":[{"name":"","code":"GET /sms/1/inbox/reports HTTP/1.1\nHost: api.infobip.com\nAuthorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==\nAccept: application/json","language":"json"}]},"auth":"required","params":[{"_id":"55196774eaa2ed2f002134cb","ref":"","in":"query","required":false,"desc":"Maximum number of received messages that will be returned.. Default value is **50**. Maximum value for this parameter is **10000**.","default":"","type":"int","name":"limit"}],"url":"/sms/:version/inbox/reports"},"isReference":true,"order":0,"body":"Besides sending SMS to your customers, you will also need an elegant solution for your customers to contact you back. After all, real dialog happens only when messages flow in both directions. Having an option to **receive SMS from your customers** can open a whole new range of possibilities for your organization!\n\nOne time setup for receiving messages consists of three easy steps.\n1. [Purchase number for receiving messages](#step-1-purchase-phone-number-for-receiving-message)\n2. [Setup Configuration container](#step-2-configuration-container-setup)\n3. [Setup Action method](#step-3-action-setup) \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/35d0aac-sms2.PNG\",\n        \"sms2.PNG\",\n        491,\n        90,\n        \"#dfd8d6\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Receiving the messages\",\n  \"body\": \"After the three-step setup you can start receiving incoming messages by using any of two available methods:\\n1. [Forward method](/docs/forward-received-messages) - messages are forwarded to your system in real time\\n3. [Pull method](/docs/pull-received-messages) - messages can be collected by API call\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 1: Purchase phone number for receiving messages\"\n}\n[/block]\nIn order to receive messages, you will need a number which has the ability to receive messages. \n\nThere are two basic types of numbers:\n* **Virtual Long Number (VLN)** - a standard looking phone number most often not different than any other personal phone number (eg. 441212859469).\n* **Short code** - number containing fewer digits than VLN and therefore more distinctive looking, with no country and network prefix, great for getting extra attention from your customers (eg. 32456).\n\nBoth types of numbers best operate on a country level so you might need to get multiple numbers if your organization operates in multiple countries.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Phone number API\",\n  \"body\": \"Use [**Phone number API**](/v1/docs/phone-number) to purchase and manage your numbers.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Short code\",\n  \"body\": \"Short codes cannot be purchased over the API. Please contact your account manager for more information.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 2: Configuration container setup\"\n}\n[/block]\nEach number you own can be configured to handle different scenarios for receiving messages. Rules are set on **Configuration **level and delivery methods for each rule are is set on **Action **level.\n\nEach number can have** one or more** Configurations and each Configuration can be associated with the **keyword**. Keywords **must be unique** on number level.\n\n**First word** of each received message is compared against Configuration keywords, and if matched, message delivery method described within Configuration Action will be used to deliver the message.\n\n###Example\nYour company would like to hear from your customers if they like your latest service. You decide to send out a message with simple yes or no question.\n\n```\nDear customers, we were wondering if you liked our latest product. Please answer to this message with simple YES or NO and add an additional comment if you have one.\n```\n\nConsider the following setup of your number on Infobip platform.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/56c7c02-sms3.PNG\",\n        \"sms3.PNG\",\n        500,\n        295,\n        \"#ded9d7\"\n      ]\n    }\n  ]\n}\n[/block]\nNow let's see what wold happened when you receive different replays from your customers.\n\n```\nOh YES, of course, I love your product! Keep up the good work!\n```\nThe message like this would match Configuration 1 since it **does not start** with **YES **or **NO **keywords. On Action level **Pull method** is defined which means that you will be able to access this messages by calling the [**Pull API method**](/docs/pull-received-messages).\n\nLet's examine this reply\n```\nYES! I love your product. Thank you.\n``` \nThe message starts with the **YES **keyword which means that Configuration 2 will be used to handle incoming message. Action inside Configuration 2 has a **Forward **URL defined so Infobip platform will initiate a [**HTTP POST or HTTP GET request**](/docs/forward-received-messages) and send message inside of the request body in JSON format if you choose POST, or through the URL parameters (query string) if you choose GET.\n\nIn order for this to work you need to set up a web page which will listen for requests and accept received messages. URL of the page needs to be provided during the Action setup.\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Configuration container API\",\n  \"body\": \"We offer a complete set of Configuration management tools over our API. Visit [**Configuration documentation**](/docs/message-configuration) to learn more.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 3: Action setup\"\n}\n[/block]\nActions live inside Configuration containers. When creating a new Action you must choose one of two possible message delivery methods:\n1. Pull\n2. Forward\n\nThere can be only one Action inside of the each Configuration container. If an incoming message matches the rule of the Configuration container, selected Action delivery method will be used to deliver the incoming message to your platform.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Action API\",\n  \"body\": \"We offer a complete set of Action management tools over our API. Visit [**Action documentation**](/docs/action) to learn more.\"\n}\n[/block]\n##Pull method\nPull method means that all messages received at your number will be saved in Infobip message inbox. Messages that we collect will patiently sit there until you decide to collect them. Messages can be collected by calling our Pull API method.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Pull API method\",\n  \"body\": \"Messages can be collected over the [**Pull API method**](/docs/pull-received-messages) only once! This means that with each API call you will only get the new messages that arrived after the previous API call.\"\n}\n[/block]\n##Http Forward method\nWith this method, you can receive incoming messages in real time. In order for this to work, you need to expose a web page and listen for HTTP request. URL of the page must be provided during Action setup process. \n\nEvery time a new message is received on your number, we will initiate an HTTP request which will contain the received message. \n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Forward method\",\n  \"body\": \"Find out how to receive forwarded messages in [**Receive forwarded messages**](/docs/forward-received-messages) documentation page.\"\n}\n[/block]","excerpt":"Learn how to receive SMS messages sent by your customers","slug":"receive-sms-introduction","type":"basic","title":"Receiving messages: Introduction"}

Receiving messages: Introduction

Learn how to receive SMS messages sent by your customers

Besides sending SMS to your customers, you will also need an elegant solution for your customers to contact you back. After all, real dialog happens only when messages flow in both directions. Having an option to **receive SMS from your customers** can open a whole new range of possibilities for your organization! One time setup for receiving messages consists of three easy steps. 1. [Purchase number for receiving messages](#step-1-purchase-phone-number-for-receiving-message) 2. [Setup Configuration container](#step-2-configuration-container-setup) 3. [Setup Action method](#step-3-action-setup) [block:image] { "images": [ { "image": [ "https://files.readme.io/35d0aac-sms2.PNG", "sms2.PNG", 491, 90, "#dfd8d6" ] } ] } [/block] [block:callout] { "type": "info", "title": "Receiving the messages", "body": "After the three-step setup you can start receiving incoming messages by using any of two available methods:\n1. [Forward method](/docs/forward-received-messages) - messages are forwarded to your system in real time\n3. [Pull method](/docs/pull-received-messages) - messages can be collected by API call" } [/block] [block:api-header] { "type": "basic", "title": "Step 1: Purchase phone number for receiving messages" } [/block] In order to receive messages, you will need a number which has the ability to receive messages. There are two basic types of numbers: * **Virtual Long Number (VLN)** - a standard looking phone number most often not different than any other personal phone number (eg. 441212859469). * **Short code** - number containing fewer digits than VLN and therefore more distinctive looking, with no country and network prefix, great for getting extra attention from your customers (eg. 32456). Both types of numbers best operate on a country level so you might need to get multiple numbers if your organization operates in multiple countries. [block:callout] { "type": "warning", "title": "Phone number API", "body": "Use [**Phone number API**](/v1/docs/phone-number) to purchase and manage your numbers." } [/block] [block:callout] { "type": "info", "title": "Short code", "body": "Short codes cannot be purchased over the API. Please contact your account manager for more information." } [/block] [block:api-header] { "type": "basic", "title": "Step 2: Configuration container setup" } [/block] Each number you own can be configured to handle different scenarios for receiving messages. Rules are set on **Configuration **level and delivery methods for each rule are is set on **Action **level. Each number can have** one or more** Configurations and each Configuration can be associated with the **keyword**. Keywords **must be unique** on number level. **First word** of each received message is compared against Configuration keywords, and if matched, message delivery method described within Configuration Action will be used to deliver the message. ###Example Your company would like to hear from your customers if they like your latest service. You decide to send out a message with simple yes or no question. ``` Dear customers, we were wondering if you liked our latest product. Please answer to this message with simple YES or NO and add an additional comment if you have one. ``` Consider the following setup of your number on Infobip platform. [block:image] { "images": [ { "image": [ "https://files.readme.io/56c7c02-sms3.PNG", "sms3.PNG", 500, 295, "#ded9d7" ] } ] } [/block] Now let's see what wold happened when you receive different replays from your customers. ``` Oh YES, of course, I love your product! Keep up the good work! ``` The message like this would match Configuration 1 since it **does not start** with **YES **or **NO **keywords. On Action level **Pull method** is defined which means that you will be able to access this messages by calling the [**Pull API method**](/docs/pull-received-messages). Let's examine this reply ``` YES! I love your product. Thank you. ``` The message starts with the **YES **keyword which means that Configuration 2 will be used to handle incoming message. Action inside Configuration 2 has a **Forward **URL defined so Infobip platform will initiate a [**HTTP POST or HTTP GET request**](/docs/forward-received-messages) and send message inside of the request body in JSON format if you choose POST, or through the URL parameters (query string) if you choose GET. In order for this to work you need to set up a web page which will listen for requests and accept received messages. URL of the page needs to be provided during the Action setup. [block:callout] { "type": "warning", "title": "Configuration container API", "body": "We offer a complete set of Configuration management tools over our API. Visit [**Configuration documentation**](/docs/message-configuration) to learn more." } [/block] [block:api-header] { "type": "basic", "title": "Step 3: Action setup" } [/block] Actions live inside Configuration containers. When creating a new Action you must choose one of two possible message delivery methods: 1. Pull 2. Forward There can be only one Action inside of the each Configuration container. If an incoming message matches the rule of the Configuration container, selected Action delivery method will be used to deliver the incoming message to your platform. [block:callout] { "type": "warning", "title": "Action API", "body": "We offer a complete set of Action management tools over our API. Visit [**Action documentation**](/docs/action) to learn more." } [/block] ##Pull method Pull method means that all messages received at your number will be saved in Infobip message inbox. Messages that we collect will patiently sit there until you decide to collect them. Messages can be collected by calling our Pull API method. [block:callout] { "type": "warning", "title": "Pull API method", "body": "Messages can be collected over the [**Pull API method**](/docs/pull-received-messages) only once! This means that with each API call you will only get the new messages that arrived after the previous API call." } [/block] ##Http Forward method With this method, you can receive incoming messages in real time. In order for this to work, you need to expose a web page and listen for HTTP request. URL of the page must be provided during Action setup process. Every time a new message is received on your number, we will initiate an HTTP request which will contain the received message. [block:callout] { "type": "warning", "title": "Forward method", "body": "Find out how to receive forwarded messages in [**Receive forwarded messages**](/docs/forward-received-messages) documentation page." } [/block]