{"_id":"565dc58cfd2d960d00a3eef9","__v":28,"createdAt":"2015-12-01T16:06:36.165Z","link_external":false,"sync_unique":"","user":"565dbcc760497d1700eccdaf","version":"565dc58afd2d960d00a3eef6","excerpt":"This page will help you get started with Messaging REST API. You'll be up and running in a jiffy!","githubsync":"","link_url":"","type":"basic","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"hidden":false,"isReference":false,"order":0,"project":"565dc58afd2d960d00a3eef3","body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Overview\"\n}\n[/block]\nSending a text message using our Messaging REST API essentially boils down to\n* encoding your credentials into the authorization header,\n* preparing the header content-types,\n* creating a JSON-formatted request body\n* sending that HTTP request to Messaging REST's /messages endpoint.\n\nThe HTTP response returned will be JSON-formatted as well and will - if everything goes according to plan - contain a\n* unique message id assigned by Messaging REST for future reference and\n* the API version, which was used for that request.\n\nOtherwise, HTTP response body returned will contain a detailed JSON-formatted error description.\n\nIf you want to process delivery notifications for messages, you need to setup a HTTP server that receives delivery notifications.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Pre-conditions\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Important!\",\n  \"body\": \"Before you get started you need to obtain a messaging account at LINK Mobility. Therefore you need to call our hotline or send us an e-mail with your desired account name (which is later your username which needs to be put into the BasicAuth header).\\n\\nYou can use the following touchpoints for this:\\n\\n**Hotline:** [+49 40 88880844](callto:+494088880844)\\n**E-Mail:**  support@linkmobility.de\\n\\nOur team creates a new messaging account for you. The password will be generated and sent back to you in any case.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Header\"\n}\n[/block]\n- **Content-Type**:\nThe MIME type of the body of the request.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Content-Type:application/json\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n- **Accept**:\nContent-Types, that are acceptable for the response.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Accept:application/json\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authorization\"\n}\n[/block]\nAll our connections are encrypted and are protected with HTTP Basic Auth. You need to provide your encoded credentials in the authorization header (Based on the Base64 schema).\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Encryption of Basic Auth\",\n  \"body\": \"As the connection is SSL secured the HTTP Basic Auth Header is also encrypted. It is not possible to read the authentication header from the request.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Authorization: Basic [encoded credentials]\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Basic sequence sending messages and receiving notifications\"\n}\n[/block]\nThis API allows you to send a message (SMS) to another destination internationally. While sending a message, you may want to get informed about the delivery status of your message. Therefore, this API offers the functionality to add a so-called \"callback URL\" to your request. This callback URL is used to send delivery notifications back to your system asynchronously. Therefore, you need to set up a server which listens on this URL and consumes JSON bodies.\n\nWe'll give you 3 short examples how this works:\n\n**Example 1** (up to 160 normal characters, using GSM 7bit charset):\n- Send a message through the REST API and provide a valid callback URL.\n- The API resource receives the message and forwards it to our internal messaging system.\n- As soon as the status for the message changes, the REST API sends a notification JSON object to the given callback URL.\n- Status changes are: NO_STATUS, BUFFERED, DELIVERED, NOT_DELIVERED\n\n**Example 2** (more than 160 characters)\n- Send a message through the REST API and provide a valid callback URL.\n- The API resource receives the message and forwards it to our internal messaging system.\n- The messaging backend detects, that this message is more than 1 SMS and will split the message according to the network operator's specific settings.\n- For **each** part of the message (for each SMS) the Messaging REST API will call the callbackURL for each status change of the different parts.\n\n**Example 3** (no callback)\n- Send a message through the REST API and provide either an empty callback URL or not existing callback URL parameter.\n- The API resource receives the message and forwards it to our internal messaging system.\n- The backend will not send any delivery notifications to your system and the delivery notifications will be discarded.","category":"565dc58bfd2d960d00a3eef7","slug":"getting-started","title":"Getting Started","updates":[],"next":{"description":"","pages":[]},"parentDoc":null,"childrenPages":[]}

Getting Started

This page will help you get started with Messaging REST API. You'll be up and running in a jiffy!

[block:api-header] { "type": "basic", "title": "Overview" } [/block] Sending a text message using our Messaging REST API essentially boils down to * encoding your credentials into the authorization header, * preparing the header content-types, * creating a JSON-formatted request body * sending that HTTP request to Messaging REST's /messages endpoint. The HTTP response returned will be JSON-formatted as well and will - if everything goes according to plan - contain a * unique message id assigned by Messaging REST for future reference and * the API version, which was used for that request. Otherwise, HTTP response body returned will contain a detailed JSON-formatted error description. If you want to process delivery notifications for messages, you need to setup a HTTP server that receives delivery notifications. [block:api-header] { "type": "basic", "title": "Pre-conditions" } [/block] [block:callout] { "type": "info", "title": "Important!", "body": "Before you get started you need to obtain a messaging account at LINK Mobility. Therefore you need to call our hotline or send us an e-mail with your desired account name (which is later your username which needs to be put into the BasicAuth header).\n\nYou can use the following touchpoints for this:\n\n**Hotline:** [+49 40 88880844](callto:+494088880844)\n**E-Mail:** support@linkmobility.de\n\nOur team creates a new messaging account for you. The password will be generated and sent back to you in any case." } [/block] [block:api-header] { "type": "basic", "title": "Header" } [/block] - **Content-Type**: The MIME type of the body of the request. [block:code] { "codes": [ { "code": "Content-Type:application/json", "language": "text" } ] } [/block] - **Accept**: Content-Types, that are acceptable for the response. [block:code] { "codes": [ { "code": "Accept:application/json", "language": "text" } ] } [/block] [block:api-header] { "type": "basic", "title": "Authorization" } [/block] All our connections are encrypted and are protected with HTTP Basic Auth. You need to provide your encoded credentials in the authorization header (Based on the Base64 schema). [block:callout] { "type": "info", "title": "Encryption of Basic Auth", "body": "As the connection is SSL secured the HTTP Basic Auth Header is also encrypted. It is not possible to read the authentication header from the request." } [/block] [block:code] { "codes": [ { "code": "Authorization: Basic [encoded credentials]", "language": "text" } ] } [/block] [block:api-header] { "type": "basic", "title": "Basic sequence sending messages and receiving notifications" } [/block] This API allows you to send a message (SMS) to another destination internationally. While sending a message, you may want to get informed about the delivery status of your message. Therefore, this API offers the functionality to add a so-called "callback URL" to your request. This callback URL is used to send delivery notifications back to your system asynchronously. Therefore, you need to set up a server which listens on this URL and consumes JSON bodies. We'll give you 3 short examples how this works: **Example 1** (up to 160 normal characters, using GSM 7bit charset): - Send a message through the REST API and provide a valid callback URL. - The API resource receives the message and forwards it to our internal messaging system. - As soon as the status for the message changes, the REST API sends a notification JSON object to the given callback URL. - Status changes are: NO_STATUS, BUFFERED, DELIVERED, NOT_DELIVERED **Example 2** (more than 160 characters) - Send a message through the REST API and provide a valid callback URL. - The API resource receives the message and forwards it to our internal messaging system. - The messaging backend detects, that this message is more than 1 SMS and will split the message according to the network operator's specific settings. - For **each** part of the message (for each SMS) the Messaging REST API will call the callbackURL for each status change of the different parts. **Example 3** (no callback) - Send a message through the REST API and provide either an empty callback URL or not existing callback URL parameter. - The API resource receives the message and forwards it to our internal messaging system. - The backend will not send any delivery notifications to your system and the delivery notifications will be discarded.
[block:api-header] { "type": "basic", "title": "Overview" } [/block] Sending a text message using our Messaging REST API essentially boils down to * encoding your credentials into the authorization header, * preparing the header content-types, * creating a JSON-formatted request body * sending that HTTP request to Messaging REST's /messages endpoint. The HTTP response returned will be JSON-formatted as well and will - if everything goes according to plan - contain a * unique message id assigned by Messaging REST for future reference and * the API version, which was used for that request. Otherwise, HTTP response body returned will contain a detailed JSON-formatted error description. If you want to process delivery notifications for messages, you need to setup a HTTP server that receives delivery notifications. [block:api-header] { "type": "basic", "title": "Pre-conditions" } [/block] [block:callout] { "type": "info", "title": "Important!", "body": "Before you get started you need to obtain a messaging account at LINK Mobility. Therefore you need to call our hotline or send us an e-mail with your desired account name (which is later your username which needs to be put into the BasicAuth header).\n\nYou can use the following touchpoints for this:\n\n**Hotline:** [+49 40 88880844](callto:+494088880844)\n**E-Mail:** support@linkmobility.de\n\nOur team creates a new messaging account for you. The password will be generated and sent back to you in any case." } [/block] [block:api-header] { "type": "basic", "title": "Header" } [/block] - **Content-Type**: The MIME type of the body of the request. [block:code] { "codes": [ { "code": "Content-Type:application/json", "language": "text" } ] } [/block] - **Accept**: Content-Types, that are acceptable for the response. [block:code] { "codes": [ { "code": "Accept:application/json", "language": "text" } ] } [/block] [block:api-header] { "type": "basic", "title": "Authorization" } [/block] All our connections are encrypted and are protected with HTTP Basic Auth. You need to provide your encoded credentials in the authorization header (Based on the Base64 schema). [block:callout] { "type": "info", "title": "Encryption of Basic Auth", "body": "As the connection is SSL secured the HTTP Basic Auth Header is also encrypted. It is not possible to read the authentication header from the request." } [/block] [block:code] { "codes": [ { "code": "Authorization: Basic [encoded credentials]", "language": "text" } ] } [/block] [block:api-header] { "type": "basic", "title": "Basic sequence sending messages and receiving notifications" } [/block] This API allows you to send a message (SMS) to another destination internationally. While sending a message, you may want to get informed about the delivery status of your message. Therefore, this API offers the functionality to add a so-called "callback URL" to your request. This callback URL is used to send delivery notifications back to your system asynchronously. Therefore, you need to set up a server which listens on this URL and consumes JSON bodies. We'll give you 3 short examples how this works: **Example 1** (up to 160 normal characters, using GSM 7bit charset): - Send a message through the REST API and provide a valid callback URL. - The API resource receives the message and forwards it to our internal messaging system. - As soon as the status for the message changes, the REST API sends a notification JSON object to the given callback URL. - Status changes are: NO_STATUS, BUFFERED, DELIVERED, NOT_DELIVERED **Example 2** (more than 160 characters) - Send a message through the REST API and provide a valid callback URL. - The API resource receives the message and forwards it to our internal messaging system. - The messaging backend detects, that this message is more than 1 SMS and will split the message according to the network operator's specific settings. - For **each** part of the message (for each SMS) the Messaging REST API will call the callbackURL for each status change of the different parts. **Example 3** (no callback) - Send a message through the REST API and provide either an empty callback URL or not existing callback URL parameter. - The API resource receives the message and forwards it to our internal messaging system. - The backend will not send any delivery notifications to your system and the delivery notifications will be discarded.
{"_id":"56656d1eb6c0f60d00eae416","updates":["5677c212efb5ea0d005bbaa3","568bf1cffe6fcc0d006dc98b","56e19aaf686c7d2000860713"],"sync_unique":"","api":{"auth":"required","params":[],"results":{"codes":[{"code":"{}","name":"","status":200,"language":"json"},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"excerpt":"Simple example of a request using cURL.","hidden":false,"isReference":false,"__v":21,"body":"Our Messaging REST-API is a simple web service for sending text messages - for now via SMS - that strives for\n* simplicity\n* ease to use\n* security\n\nBefore starting with our whole documentation, let's have a quick look on an example request to our API using cURL.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Request\"\n}\n[/block]\nBy providing your **credentials**, **header**-information and the parameters **from**, **to** and the **body** you are done! Send your HTTP POST to the following URL: https://messaging.whatevermobile.com/messaging/1.0/messages\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"cat << EOF | curl -u 'user:password' \\\\\\n--header 'Content-Type:application/json' \\\\\\n--header 'Accept:application/json' \\\\\\n--data @- https://messaging.whatevermobile.com/messaging/1.0/messages\\n{\\n\\t\\\"from\\\":\\\"John Doe\\\",\\n\\t\\\"to\\\":\\\"+491602345678\\\",\\n\\t\\\"body\\\":\\\"Hey Jane, your two-factor code is 352343.\\\"\\n}\\nEOF\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Encoding and character set\",\n  \"body\": \"Please send your message in UTF-8 encoding. Only characters of the GSM 7bit charset are allowed.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Important\",\n  \"body\": \"Before you get started you need to obtain a messaging account at whatever mobile. For details see [Pre-conditions](#pre-conditions) section below.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response\"\n}\n[/block]\nIf your request was successfully delivered to our system, you will receive a response containing the version of the API you used and an unique identifier of your message.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"apiVersion\\\":\\\"1.0\\\",\\n  \\\"id\\\":\\\"2927942094397992960\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","createdAt":"2015-12-07T11:27:26.193Z","link_external":false,"order":1,"project":"565dc58afd2d960d00a3eef3","title":"Example","type":"basic","version":"565dc58afd2d960d00a3eef6","user":"565dbcc760497d1700eccdaf","githubsync":"","link_url":"","slug":"example","category":"565dc58bfd2d960d00a3eef7","next":{"description":"","pages":[]},"parentDoc":null,"childrenPages":[]}

Example

Simple example of a request using cURL.

Our Messaging REST-API is a simple web service for sending text messages - for now via SMS - that strives for * simplicity * ease to use * security Before starting with our whole documentation, let's have a quick look on an example request to our API using cURL. [block:api-header] { "type": "basic", "title": "Request" } [/block] By providing your **credentials**, **header**-information and the parameters **from**, **to** and the **body** you are done! Send your HTTP POST to the following URL: https://messaging.whatevermobile.com/messaging/1.0/messages [block:code] { "codes": [ { "code": "cat << EOF | curl -u 'user:password' \\\n--header 'Content-Type:application/json' \\\n--header 'Accept:application/json' \\\n--data @- https://messaging.whatevermobile.com/messaging/1.0/messages\n{\n\t\"from\":\"John Doe\",\n\t\"to\":\"+491602345678\",\n\t\"body\":\"Hey Jane, your two-factor code is 352343.\"\n}\nEOF", "language": "shell" } ] } [/block] [block:callout] { "type": "info", "title": "Encoding and character set", "body": "Please send your message in UTF-8 encoding. Only characters of the GSM 7bit charset are allowed." } [/block] [block:callout] { "type": "info", "title": "Important", "body": "Before you get started you need to obtain a messaging account at whatever mobile. For details see [Pre-conditions](#pre-conditions) section below." } [/block] [block:api-header] { "type": "basic", "title": "Response" } [/block] If your request was successfully delivered to our system, you will receive a response containing the version of the API you used and an unique identifier of your message. [block:code] { "codes": [ { "code": "{\n \"apiVersion\":\"1.0\",\n \"id\":\"2927942094397992960\"\n}", "language": "json" } ] } [/block]
Our Messaging REST-API is a simple web service for sending text messages - for now via SMS - that strives for * simplicity * ease to use * security Before starting with our whole documentation, let's have a quick look on an example request to our API using cURL. [block:api-header] { "type": "basic", "title": "Request" } [/block] By providing your **credentials**, **header**-information and the parameters **from**, **to** and the **body** you are done! Send your HTTP POST to the following URL: https://messaging.whatevermobile.com/messaging/1.0/messages [block:code] { "codes": [ { "code": "cat << EOF | curl -u 'user:password' \\\n--header 'Content-Type:application/json' \\\n--header 'Accept:application/json' \\\n--data @- https://messaging.whatevermobile.com/messaging/1.0/messages\n{\n\t\"from\":\"John Doe\",\n\t\"to\":\"+491602345678\",\n\t\"body\":\"Hey Jane, your two-factor code is 352343.\"\n}\nEOF", "language": "shell" } ] } [/block] [block:callout] { "type": "info", "title": "Encoding and character set", "body": "Please send your message in UTF-8 encoding. Only characters of the GSM 7bit charset are allowed." } [/block] [block:callout] { "type": "info", "title": "Important", "body": "Before you get started you need to obtain a messaging account at whatever mobile. For details see [Pre-conditions](#pre-conditions) section below." } [/block] [block:api-header] { "type": "basic", "title": "Response" } [/block] If your request was successfully delivered to our system, you will receive a response containing the version of the API you used and an unique identifier of your message. [block:code] { "codes": [ { "code": "{\n \"apiVersion\":\"1.0\",\n \"id\":\"2927942094397992960\"\n}", "language": "json" } ] } [/block]
{"_id":"565dc8d794f30d0d00d1f39a","excerpt":"","slug":"send-a-sms","type":"post","__v":3,"api":{"method":"post","params":[{"_id":"565dc8d794f30d0d00d1f39d","ref":"","in":"body","required":true,"desc":"The mobile phone number of your destination. The field has to be formatted according to the E.164  standard. (e.g. +4916094839610)","default":"","type":"string","name":"to"},{"_id":"565dc8d794f30d0d00d1f39c","ref":"","in":"body","required":true,"desc":"Usually the company name, where the text message comes from. Amount of max. 11 alphanumeric characters allowed.","default":"","type":"string","name":"from"},{"_id":"565dc8d794f30d0d00d1f39b","ref":"","in":"body","required":true,"desc":"The content of your text message. Please remember, that the length of a text message is limited to  160 7-bit characters. More content (concatenated) and special characters decrease the amount of  possible characters.","default":"","type":"string","name":"body"},{"_id":"565f09cf7f93280d0052ce51","ref":"","in":"body","required":false,"desc":"This URL is used to transmit delivery notifications back to your system. If you leave this parameter empty OR this parameter is not transmitted, no delivery notifications will be sent back to your system.","default":"","type":"string","name":"callbackUrl"}],"results":{"codes":[{"status":200,"language":"json","code":"{\n \"apiVersion\": \"1.0\",\n \"id\": \"01234567898889998\"\n}","name":""},{"status":400,"language":"json","code":"{\n \"apiVersion\": \"1.0\",\n \"errorCode\": \"11\",\n \"errorDetails\": {\n \"description\": \"Field 'to' must be a telephone number in international format\n(E.164), e.g. '+4916094839610'.\",\n \"link\": \"https://messaging.errors.whatevermobile.com/errors/11\"\n },\n \"effectiveRequest\": {\n \"from\": \"John Doe\",\n \"to\": \"016094839610 \",\n \"body\": \"Hey Jane, your two-factor code is 352343.\"\n }\n}"},{"code":"If your credentials are wrong or missing","language":"text","status":401},{"status":500,"language":"json","code":"{\n \"apiVersion\": \"1.0\",\n \"errorCode\": \"11\",\n \"errorDetails\": {\n \"description\": \"Field 'to' must be a telephone number in international format\n(E.164), e.g. '+4916094839610'.\",\n \"link\": \"https://messaging.errors.whatevermobile.com/errors/11\"\n },\n \"effectiveRequest\": {\n \"from\": \"John Doe\",\n \"to\": \"016094839610 \",\n \"body\": \"Hey Jane, your two-factor code is 352343.\"\n }\n}"}]},"settings":"","url":"/messaging/1.0/messages","auth":"required","examples":{"codes":[{"language":"json","code":"{\n \"from\": \"John Doe\",\n \"to\": \"+491602345678\",\n \"body\": \"Hey Jane, your two-factor code is 352343.\"\n }","name":""}]}},"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Success JSON parameters\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"apiVersion\",\n    \"0-1\": \"String\",\n    \"0-2\": \"Returns the API version used for the request.\",\n    \"1-0\": \"id\",\n    \"1-1\": \"String\",\n    \"1-2\": \"This unique ID is generated by the backend messaging system. This ID can be helpful in case of any investigations. It becomes important if you desire delivery notifications - as delivery notifications refer to the original ID returned by this resource call.\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Error Response\"\n}\n[/block]\nIn case of a failure, the response provides additional information for debugging. We provide you the interpolated request, for detecting differences after your request has been processed through our system.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"apiVersion\\\": \\\"1.0\\\",\\n  \\\"errorCode\\\": \\\"11\\\",\\n  \\\"errorDetails\\\": {\\n    \\\"description\\\": \\\"Field 'to' must be a telephone number in international format\\n(E.164), e.g. '+491602345678'.\\\",\\n    \\\"link\\\": \\\"https://messaging.errors.whatevermobile.com/errors/11\\\"\\n    },\\n  \\\"effectiveRequest\\\": {\\n    \\\"from\\\": \\\"John Doe\\\",\\n    \\\"to\\\": \\\"01602345678\\\",\\n    \\\"body\\\": \\\"Hey Jane, your two-factor code is 352343.\\\"\\n\\t} \\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Error Codes\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"In case one of the following error codes is returned no delivery notification will be sent back. These error codes are final states!\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Code\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"Retry?*\",\n    \"h-3\": \"Http Status\",\n    \"0-0\": \"01\",\n    \"0-1\": \"Parameter \\\"from\\\" is missing\",\n    \"0-2\": \"no\",\n    \"0-3\": \"400\",\n    \"1-0\": \"02\",\n    \"1-1\": \"Parameter \\\"from\\\" not in alphanumeric or international format\",\n    \"1-2\": \"no\",\n    \"1-3\": \"400\",\n    \"2-0\": \"03\",\n    \"2-1\": \"Parameter \\\"from\\\" is in alphanumeric format and too long\",\n    \"2-2\": \"no\",\n    \"2-3\": \"400\",\n    \"3-0\": \"04\",\n    \"3-1\": \"Parameter \\\"from\\\" is in international format and too short\",\n    \"3-2\": \"no\",\n    \"3-3\": \"400\",\n    \"4-0\": \"05\",\n    \"4-1\": \"Parameter \\\"from\\\" is in international format and too long\",\n    \"4-2\": \"no\",\n    \"4-3\": \"400\",\n    \"5-0\": \"10\",\n    \"5-1\": \"Parameter \\\"to\\\" is missing\",\n    \"5-2\": \"no\",\n    \"5-3\": \"400\",\n    \"6-0\": \"11\",\n    \"6-1\": \"Parameter \\\"to\\\" is not in international format\",\n    \"6-2\": \"no\",\n    \"6-3\": \"400\",\n    \"7-0\": \"12\",\n    \"7-1\": \"Parameter \\\"to\\\" is too short\",\n    \"7-2\": \"no\",\n    \"7-3\": \"400\",\n    \"8-0\": \"13\",\n    \"8-1\": \"Parameter \\\"to\\\" is too long\",\n    \"8-2\": \"no\",\n    \"8-3\": \"400\",\n    \"9-0\": \"20\",\n    \"9-1\": \"Parameter \\\"body\\\" is missing\",\n    \"9-2\": \"no\",\n    \"9-3\": \"400\",\n    \"10-0\": \"21\",\n    \"10-1\": \"Parameter \\\"body\\\" is coded in an unsupported charset - this API only supports UTF8\",\n    \"10-2\": \"no\",\n    \"10-3\": \"400\",\n    \"11-0\": \"31\",\n    \"11-1\": \"URL format is corrupted\",\n    \"11-2\": \"no\",\n    \"11-3\": \"400\",\n    \"12-0\": \"80\",\n    \"12-1\": \"Wrong or missing credentials\",\n    \"12-2\": \"no\",\n    \"12-3\": \"401\",\n    \"13-0\": \"81\",\n    \"13-1\": \"Call to messaging backend failed\",\n    \"13-2\": \"yes\",\n    \"13-3\": \"502\",\n    \"15-0\": \"90\",\n    \"15-1\": \"Malformed request\",\n    \"15-2\": \"no\",\n    \"15-3\": \"400\",\n    \"16-0\": \"91\",\n    \"16-1\": \"HTTP method not allowed\",\n    \"16-2\": \"no\",\n    \"16-3\": \"405\",\n    \"17-0\": \"92\",\n    \"17-1\": \"Unsupported MediaType\",\n    \"17-2\": \"no\",\n    \"17-3\": \"400\",\n    \"18-0\": \"99\",\n    \"18-1\": \"Generic error\",\n    \"18-2\": \"no\",\n    \"18-3\": \"500\",\n    \"14-0\": \"82\",\n    \"14-1\": \"Insufficient credit. Cannot send message.\",\n    \"14-2\": \"no\",\n    \"14-3\": \"400\"\n  },\n  \"cols\": 4,\n  \"rows\": 19\n}\n[/block]\n\\* retry with unmodified parameters","editedParams2":true,"project":"565dc58afd2d960d00a3eef3","sync_unique":"","category":"565dc58bfd2d960d00a3eef7","createdAt":"2015-12-01T16:20:39.243Z","hidden":false,"isReference":false,"link_url":"","order":2,"title":"Send a SMS","editedParams":true,"githubsync":"","link_external":false,"updates":["57580f5a8abb520e00ea7b54"],"user":"565dbcc760497d1700eccdaf","version":"565dc58afd2d960d00a3eef6","next":{"description":"","pages":[]},"parentDoc":null,"childrenPages":[]}

postSend a SMS


Body Params

to:
required
string
The mobile phone number of your destination. The field has to be formatted according to the E.164 standard. (e.g. +4916094839610)
from:
required
string
Usually the company name, where the text message comes from. Amount of max. 11 alphanumeric characters allowed.
body:
required
string
The content of your text message. Please remember, that the length of a text message is limited to 160 7-bit characters. More content (concatenated) and special characters decrease the amount of possible characters.
callbackUrl:
string
This URL is used to transmit delivery notifications back to your system. If you leave this parameter empty OR this parameter is not transmitted, no delivery notifications will be sent back to your system.
[block:api-header] { "type": "basic", "title": "Success JSON parameters" } [/block] [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "apiVersion", "0-1": "String", "0-2": "Returns the API version used for the request.", "1-0": "id", "1-1": "String", "1-2": "This unique ID is generated by the backend messaging system. This ID can be helpful in case of any investigations. It becomes important if you desire delivery notifications - as delivery notifications refer to the original ID returned by this resource call." }, "cols": 3, "rows": 2 } [/block] [block:api-header] { "type": "basic", "title": "Error Response" } [/block] In case of a failure, the response provides additional information for debugging. We provide you the interpolated request, for detecting differences after your request has been processed through our system. [block:code] { "codes": [ { "code": "{\n\t\"apiVersion\": \"1.0\",\n \"errorCode\": \"11\",\n \"errorDetails\": {\n \"description\": \"Field 'to' must be a telephone number in international format\n(E.164), e.g. '+491602345678'.\",\n \"link\": \"https://messaging.errors.whatevermobile.com/errors/11\"\n },\n \"effectiveRequest\": {\n \"from\": \"John Doe\",\n \"to\": \"01602345678\",\n \"body\": \"Hey Jane, your two-factor code is 352343.\"\n\t} \n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Error Codes" } [/block] [block:callout] { "type": "info", "body": "In case one of the following error codes is returned no delivery notification will be sent back. These error codes are final states!" } [/block] [block:parameters] { "data": { "h-0": "Code", "h-1": "Description", "h-2": "Retry?*", "h-3": "Http Status", "0-0": "01", "0-1": "Parameter \"from\" is missing", "0-2": "no", "0-3": "400", "1-0": "02", "1-1": "Parameter \"from\" not in alphanumeric or international format", "1-2": "no", "1-3": "400", "2-0": "03", "2-1": "Parameter \"from\" is in alphanumeric format and too long", "2-2": "no", "2-3": "400", "3-0": "04", "3-1": "Parameter \"from\" is in international format and too short", "3-2": "no", "3-3": "400", "4-0": "05", "4-1": "Parameter \"from\" is in international format and too long", "4-2": "no", "4-3": "400", "5-0": "10", "5-1": "Parameter \"to\" is missing", "5-2": "no", "5-3": "400", "6-0": "11", "6-1": "Parameter \"to\" is not in international format", "6-2": "no", "6-3": "400", "7-0": "12", "7-1": "Parameter \"to\" is too short", "7-2": "no", "7-3": "400", "8-0": "13", "8-1": "Parameter \"to\" is too long", "8-2": "no", "8-3": "400", "9-0": "20", "9-1": "Parameter \"body\" is missing", "9-2": "no", "9-3": "400", "10-0": "21", "10-1": "Parameter \"body\" is coded in an unsupported charset - this API only supports UTF8", "10-2": "no", "10-3": "400", "11-0": "31", "11-1": "URL format is corrupted", "11-2": "no", "11-3": "400", "12-0": "80", "12-1": "Wrong or missing credentials", "12-2": "no", "12-3": "401", "13-0": "81", "13-1": "Call to messaging backend failed", "13-2": "yes", "13-3": "502", "15-0": "90", "15-1": "Malformed request", "15-2": "no", "15-3": "400", "16-0": "91", "16-1": "HTTP method not allowed", "16-2": "no", "16-3": "405", "17-0": "92", "17-1": "Unsupported MediaType", "17-2": "no", "17-3": "400", "18-0": "99", "18-1": "Generic error", "18-2": "no", "18-3": "500", "14-0": "82", "14-1": "Insufficient credit. Cannot send message.", "14-2": "no", "14-3": "400" }, "cols": 4, "rows": 19 } [/block] \* retry with unmodified parameters

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:api-header] { "type": "basic", "title": "Success JSON parameters" } [/block] [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "apiVersion", "0-1": "String", "0-2": "Returns the API version used for the request.", "1-0": "id", "1-1": "String", "1-2": "This unique ID is generated by the backend messaging system. This ID can be helpful in case of any investigations. It becomes important if you desire delivery notifications - as delivery notifications refer to the original ID returned by this resource call." }, "cols": 3, "rows": 2 } [/block] [block:api-header] { "type": "basic", "title": "Error Response" } [/block] In case of a failure, the response provides additional information for debugging. We provide you the interpolated request, for detecting differences after your request has been processed through our system. [block:code] { "codes": [ { "code": "{\n\t\"apiVersion\": \"1.0\",\n \"errorCode\": \"11\",\n \"errorDetails\": {\n \"description\": \"Field 'to' must be a telephone number in international format\n(E.164), e.g. '+491602345678'.\",\n \"link\": \"https://messaging.errors.whatevermobile.com/errors/11\"\n },\n \"effectiveRequest\": {\n \"from\": \"John Doe\",\n \"to\": \"01602345678\",\n \"body\": \"Hey Jane, your two-factor code is 352343.\"\n\t} \n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Error Codes" } [/block] [block:callout] { "type": "info", "body": "In case one of the following error codes is returned no delivery notification will be sent back. These error codes are final states!" } [/block] [block:parameters] { "data": { "h-0": "Code", "h-1": "Description", "h-2": "Retry?*", "h-3": "Http Status", "0-0": "01", "0-1": "Parameter \"from\" is missing", "0-2": "no", "0-3": "400", "1-0": "02", "1-1": "Parameter \"from\" not in alphanumeric or international format", "1-2": "no", "1-3": "400", "2-0": "03", "2-1": "Parameter \"from\" is in alphanumeric format and too long", "2-2": "no", "2-3": "400", "3-0": "04", "3-1": "Parameter \"from\" is in international format and too short", "3-2": "no", "3-3": "400", "4-0": "05", "4-1": "Parameter \"from\" is in international format and too long", "4-2": "no", "4-3": "400", "5-0": "10", "5-1": "Parameter \"to\" is missing", "5-2": "no", "5-3": "400", "6-0": "11", "6-1": "Parameter \"to\" is not in international format", "6-2": "no", "6-3": "400", "7-0": "12", "7-1": "Parameter \"to\" is too short", "7-2": "no", "7-3": "400", "8-0": "13", "8-1": "Parameter \"to\" is too long", "8-2": "no", "8-3": "400", "9-0": "20", "9-1": "Parameter \"body\" is missing", "9-2": "no", "9-3": "400", "10-0": "21", "10-1": "Parameter \"body\" is coded in an unsupported charset - this API only supports UTF8", "10-2": "no", "10-3": "400", "11-0": "31", "11-1": "URL format is corrupted", "11-2": "no", "11-3": "400", "12-0": "80", "12-1": "Wrong or missing credentials", "12-2": "no", "12-3": "401", "13-0": "81", "13-1": "Call to messaging backend failed", "13-2": "yes", "13-3": "502", "15-0": "90", "15-1": "Malformed request", "15-2": "no", "15-3": "400", "16-0": "91", "16-1": "HTTP method not allowed", "16-2": "no", "16-3": "405", "17-0": "92", "17-1": "Unsupported MediaType", "17-2": "no", "17-3": "400", "18-0": "99", "18-1": "Generic error", "18-2": "no", "18-3": "500", "14-0": "82", "14-1": "Insufficient credit. Cannot send message.", "14-2": "no", "14-3": "400" }, "cols": 4, "rows": 19 } [/block] \* retry with unmodified parameters
{"_id":"565f04cfbca87d0d006bc5f5","user":"565dbcc760497d1700eccdaf","excerpt":"How to handle delivery notifications for your messages.","hidden":false,"link_external":false,"updates":[],"githubsync":"","order":3,"type":"basic","project":"565dc58afd2d960d00a3eef3","slug":"receive-delivery-notifications","version":"565dc58afd2d960d00a3eef6","__v":23,"api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"What are Delivery Notifications?\"\n}\n[/block]\nA delivery notification describes the status of a single SMS. As the API expects a message body which is cutted in SMS parts by the backend system (depending on carrier that sends the message at the end) - the messaging system will send one or multiple delivery notifications for each part. There are different statuses that may occur for each part:\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"SENT\",\n  \"body\": \"The sms part has been acknowledged by the carrier and will be transmitted to the handset.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"BUFFERED\",\n  \"body\": \"The sms part is buffered at the carrier (Maybe, the handset is not reachable at the moment).\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"DELIVERED\",\n  \"body\": \"The sms part has been delivered.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"The sms part has not been delivered.\",\n  \"title\": \"NOT_DELIVERED\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Transmission of Delivery Notifications\"\n}\n[/block]\nIf a callback URL is provided when sending a message (SMS), the messaging system will send asynchronously delivery notifications for each part of the message (when sent as SMS).\n\nYou need to setup a simple REST/JSON HTTP server that is capable of receiving the following *JSON* object as **POST** method call:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"apiVersion\",\n    \"0-1\": \"String\",\n    \"0-2\": \"Which API version has been used by formerly sent request to send a message.\",\n    \"1-0\": \"messageId\",\n    \"1-1\": \"String\",\n    \"1-2\": \"This is the reference ID of the formerly sent message response (see  [Success JSON parameters](#success-json-parameters)).\",\n    \"2-0\": \"accountSid\",\n    \"2-1\": \"String\",\n    \"2-2\": \"The account SID that sent the message.\",\n    \"3-0\": \"deliveryStatus\",\n    \"3-1\": \"String\",\n    \"3-2\": \"One of the following:\\n* SENT\\n* BUFFERED\\n* DELIVERED\\n* NOT_DELIVERED\",\n    \"4-0\": \"messagePart\",\n    \"4-1\": \"Integer\",\n    \"4-2\": \"The part of the SMS the delivery notification is for.\",\n    \"5-0\": \"numberOfMessageParts\",\n    \"5-1\": \"Integer\",\n    \"5-2\": \"The overall number of SMS parts that have been sent by through the carrier.\",\n    \"6-0\": \"deliveryTimestamp\",\n    \"6-1\": \"Long\",\n    \"6-2\": \"The UNIX timestamp from the carrier when the delivery notification has been processed.\"\n  },\n  \"cols\": 3,\n  \"rows\": 7\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Redelivery of notifications\",\n  \"body\": \"The backend tries to deliver the notifications as soon as the operator sends them out. When the callback URL is not available or the server that listens for notifications is returning other than HttpStatus 200, the delivery will be retried two more times with an interval of 15 minutes.\\n\\nNotifications are discarded when retries are exhausted.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Example\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"apiVersion\\\": \\\"1.0\\\",\\n \\t\\\"messageId\\\": \\\"987654321\\\",\\n\\t\\\"accountSid\\\": \\\"test\\\",\\n \\t\\\"deliveryStatus\\\": \\\"DELIVERED\\\",\\n \\t\\\"messagePart\\\": 1,\\n \\t\\\"numberOfMessageParts\\\": 1,\\n \\t\\\"deliveryTimestamp\\\": 1449238656\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","category":"565dc58bfd2d960d00a3eef7","title":"Delivery Notifications","createdAt":"2015-12-02T14:48:47.753Z","isReference":false,"link_url":"","sync_unique":"","parentDoc":null,"childrenPages":[]}

Delivery Notifications

How to handle delivery notifications for your messages.

[block:api-header] { "type": "basic", "title": "What are Delivery Notifications?" } [/block] A delivery notification describes the status of a single SMS. As the API expects a message body which is cutted in SMS parts by the backend system (depending on carrier that sends the message at the end) - the messaging system will send one or multiple delivery notifications for each part. There are different statuses that may occur for each part: [block:callout] { "type": "info", "title": "SENT", "body": "The sms part has been acknowledged by the carrier and will be transmitted to the handset." } [/block] [block:callout] { "type": "warning", "title": "BUFFERED", "body": "The sms part is buffered at the carrier (Maybe, the handset is not reachable at the moment)." } [/block] [block:callout] { "type": "success", "title": "DELIVERED", "body": "The sms part has been delivered." } [/block] [block:callout] { "type": "danger", "body": "The sms part has not been delivered.", "title": "NOT_DELIVERED" } [/block] [block:api-header] { "type": "basic", "title": "Transmission of Delivery Notifications" } [/block] If a callback URL is provided when sending a message (SMS), the messaging system will send asynchronously delivery notifications for each part of the message (when sent as SMS). You need to setup a simple REST/JSON HTTP server that is capable of receiving the following *JSON* object as **POST** method call: [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "apiVersion", "0-1": "String", "0-2": "Which API version has been used by formerly sent request to send a message.", "1-0": "messageId", "1-1": "String", "1-2": "This is the reference ID of the formerly sent message response (see [Success JSON parameters](#success-json-parameters)).", "2-0": "accountSid", "2-1": "String", "2-2": "The account SID that sent the message.", "3-0": "deliveryStatus", "3-1": "String", "3-2": "One of the following:\n* SENT\n* BUFFERED\n* DELIVERED\n* NOT_DELIVERED", "4-0": "messagePart", "4-1": "Integer", "4-2": "The part of the SMS the delivery notification is for.", "5-0": "numberOfMessageParts", "5-1": "Integer", "5-2": "The overall number of SMS parts that have been sent by through the carrier.", "6-0": "deliveryTimestamp", "6-1": "Long", "6-2": "The UNIX timestamp from the carrier when the delivery notification has been processed." }, "cols": 3, "rows": 7 } [/block] [block:callout] { "type": "info", "title": "Redelivery of notifications", "body": "The backend tries to deliver the notifications as soon as the operator sends them out. When the callback URL is not available or the server that listens for notifications is returning other than HttpStatus 200, the delivery will be retried two more times with an interval of 15 minutes.\n\nNotifications are discarded when retries are exhausted." } [/block] [block:api-header] { "type": "basic", "title": "Example" } [/block] [block:code] { "codes": [ { "code": "{\n \"apiVersion\": \"1.0\",\n \t\"messageId\": \"987654321\",\n\t\"accountSid\": \"test\",\n \t\"deliveryStatus\": \"DELIVERED\",\n \t\"messagePart\": 1,\n \t\"numberOfMessageParts\": 1,\n \t\"deliveryTimestamp\": 1449238656\n}", "language": "json" } ] } [/block]
[block:api-header] { "type": "basic", "title": "What are Delivery Notifications?" } [/block] A delivery notification describes the status of a single SMS. As the API expects a message body which is cutted in SMS parts by the backend system (depending on carrier that sends the message at the end) - the messaging system will send one or multiple delivery notifications for each part. There are different statuses that may occur for each part: [block:callout] { "type": "info", "title": "SENT", "body": "The sms part has been acknowledged by the carrier and will be transmitted to the handset." } [/block] [block:callout] { "type": "warning", "title": "BUFFERED", "body": "The sms part is buffered at the carrier (Maybe, the handset is not reachable at the moment)." } [/block] [block:callout] { "type": "success", "title": "DELIVERED", "body": "The sms part has been delivered." } [/block] [block:callout] { "type": "danger", "body": "The sms part has not been delivered.", "title": "NOT_DELIVERED" } [/block] [block:api-header] { "type": "basic", "title": "Transmission of Delivery Notifications" } [/block] If a callback URL is provided when sending a message (SMS), the messaging system will send asynchronously delivery notifications for each part of the message (when sent as SMS). You need to setup a simple REST/JSON HTTP server that is capable of receiving the following *JSON* object as **POST** method call: [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "apiVersion", "0-1": "String", "0-2": "Which API version has been used by formerly sent request to send a message.", "1-0": "messageId", "1-1": "String", "1-2": "This is the reference ID of the formerly sent message response (see [Success JSON parameters](#success-json-parameters)).", "2-0": "accountSid", "2-1": "String", "2-2": "The account SID that sent the message.", "3-0": "deliveryStatus", "3-1": "String", "3-2": "One of the following:\n* SENT\n* BUFFERED\n* DELIVERED\n* NOT_DELIVERED", "4-0": "messagePart", "4-1": "Integer", "4-2": "The part of the SMS the delivery notification is for.", "5-0": "numberOfMessageParts", "5-1": "Integer", "5-2": "The overall number of SMS parts that have been sent by through the carrier.", "6-0": "deliveryTimestamp", "6-1": "Long", "6-2": "The UNIX timestamp from the carrier when the delivery notification has been processed." }, "cols": 3, "rows": 7 } [/block] [block:callout] { "type": "info", "title": "Redelivery of notifications", "body": "The backend tries to deliver the notifications as soon as the operator sends them out. When the callback URL is not available or the server that listens for notifications is returning other than HttpStatus 200, the delivery will be retried two more times with an interval of 15 minutes.\n\nNotifications are discarded when retries are exhausted." } [/block] [block:api-header] { "type": "basic", "title": "Example" } [/block] [block:code] { "codes": [ { "code": "{\n \"apiVersion\": \"1.0\",\n \t\"messageId\": \"987654321\",\n\t\"accountSid\": \"test\",\n \t\"deliveryStatus\": \"DELIVERED\",\n \t\"messagePart\": 1,\n \t\"numberOfMessageParts\": 1,\n \t\"deliveryTimestamp\": 1449238656\n}", "language": "json" } ] } [/block]