Download OpenAPI specification:Download
API for omni-channel message delivery
Connection point: https://notifications.fromni.com/v3
Data format: JSON
Encoding: UTF-8
Authorization: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-Type: application/json
HTTP API has certain and predictable URLs and uses HTTP result codes for processing the error. We use JSON format for all API replies, including errors.
When calling our API, your access key must be added to header `Authorization: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Returns result of adding message to send queue and message ID if result = success. All methods for sending a message support additional parameter delivery_date. It is scheduled date and time of the message in Y-m-d H:i:s format. Scheduled time is always UTC and can’t be more than 72 hours from current time. All methods for sending a message within Russia support additional parameter daydelivery. It means that message should be delivered only within daylight hours. Time range considered as Daylight hours can be set using your Fromni account (Additional settings section). Default value is time range from 9 a.m till 8 p.m. Messages sent out of that period will wait till the earliest possible time set as Daylight hours occures.
| Content-Type required | string Example: application/json |
| Authorization required | string Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| sender required | string SenderID |
| phone required | string Phone number |
| text required | string Message text |
| ttl | number [ 60 .. 172800 ] Default: 172800 Message delivery lifetime in seconds |
| custom_id | string Client reference message ID |
| report | string Status report url |
| daydelivery | boolean Delivery within daylight hours only |
| delivery_date | string <date-time> Particular date and time for message delivery |
{- "sender": "fromni",
- "phone": "358000000000",
- "text": "Text",
- "ttl": 172800,
- "custom_id": "123",
}{- "result": "success",
- "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}{- "id": "fd698b41-7476-4478-bd1c-d74266f3cc86",
- "custom_id": "123",
- "status": "error",
- "channel": "sms",
- "error": "The text is not matched existing templates",
- "code": 1000
}| Content-Type required | string Example: application/json |
| Authorization required | string Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| sender required | string SenderID |
| phone required | string Phone number |
| text | string Message text |
| image | string Image URL (400x400 size is recommended, max. 1 Mb) |
object (Action) | |
| ttl | number [ 60 .. 86400 ] Default: 600 Message delivery lifetime in seconds |
| custom_id | string Client reference message ID |
| report | string Status report url |
| reply | string URL where to send reply from an end user |
| daydelivery | boolean Delivery within daylight hours only |
| delivery_date | string <date-time> Particular date and time for message delivery |
{- "sender": "fromni",
- "phone": "358000000000",
- "text": "Text",
- "action": {
- "title": "Button",
- "url": "string"
}, - "ttl": 600,
- "custom_id": "123",
}
{- "result": "success",
- "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}{- "id": "fd698b41-7476-4478-bd1c-d74266f3cc86",
- "custom_id": "123",
- "status": "error",
- "channel": "sms",
- "error": "The text is not matched existing templates",
- "code": 1000
}| Content-Type required | string Example: application/json |
| Authorization required | string Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| group required | number VK group identifier |
| phone required | string Phone number |
| text required | string Message text |
| ttl | number [ 60 .. 86400 ] Default: 600 Message delivery lifetime in seconds |
| custom_id | string Client reference message ID |
| report | string Status report url |
| reply | string URL where to send reply from an end user |
| daydelivery | boolean Delivery within daylight hours only |
| delivery_date | string <date-time> Particular date and time for message delivery |
{- "group": 5965316,
- "phone": "358000000000",
- "text": "Text",
- "ttl": 600,
- "custom_id": "123",
}{- "result": "success",
- "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}{- "id": "fd698b41-7476-4478-bd1c-d74266f3cc86",
- "custom_id": "123",
- "status": "error",
- "channel": "sms",
- "error": "The text is not matched existing templates",
- "code": 1000
}| Content-Type required | string Example: application/json |
| Authorization required | string Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| custom_id | string Client reference message ID |
| report | string Status report url |
| reply | string URL where to send reply from an end user |
| daydelivery | boolean Delivery within daylight hours only |
| delivery_date | string <date-time> Particular date and time for message delivery |
required | Array of objects (Route) Delivery channels route |
{- "custom_id": "123",
- "route": [
- {
- "channel": "vk",
- "group": 5965316,
- "phone": "358000000000",
- "text": "Text",
- "ttl": 600
}, - {
- "channel": "viber",
- "sender": "fromni",
- "phone": "358000000000",
- "text": "Text",
- "action": {
- "title": "Button",
- "url": "string"
}, - "ttl": 600
}, - {
- "channel": "sms",
- "sender": "fromni",
- "phone": "358000000000",
- "text": "Text",
- "ttl": 172800
}
]
}{- "result": "success",
- "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}{- "id": "fd698b41-7476-4478-bd1c-d74266f3cc86",
- "custom_id": "123",
- "status": "error",
- "channel": "sms",
- "error": "The text is not matched existing templates",
- "code": 1000
}The method simplifies the way of sending a message via several channels (omnichannel delivery). The only thing you need is to send one text message in the request. When processing a delivery routs, we will use the channels and priority of one channel over another set for your User account as default.
| Content-Type required | string Example: application/json |
| Authorization required | string Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| custom_id | string Client reference message ID |
| report | string Status report url |
| reply | string URL where to send reply from an end user |
| daydelivery | boolean Delivery within daylight hours only |
| delivery_date | string <date-time> Particular date and time for message delivery |
| sender | string SenderID |
| phone required | string Phone number |
| text required | string Message text |
| ttl | number [ 60 .. 86400 ] Default: 300 Message delivery lifetime in seconds |
{- "custom_id": "123",
- "sender": "fromni",
- "phone": "358000000000",
- "text": "Text",
- "ttl": 300
}{- "result": "success",
- "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}{- "id": "fd698b41-7476-4478-bd1c-d74266f3cc86",
- "custom_id": "123",
- "status": "error",
- "channel": "sms",
- "error": "The text is not matched existing templates",
- "code": 1000
}Queries and rules for this method are same as used for the [Omnichannel sending], but sent in the form of array.
| Content-Type required | string Example: application/json |
| Authorization required | string Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| custom_id required | string |
| report required | string |
| reply required | string |
| daydelivery | boolean |
| delivery_date | string <date-time> |
required | Array of objects (Desc) |
[- {
- "custom_id": "123",
- "route": [
- {
- "channel": "vk",
- "group": 5965316,
- "phone": "358000000000",
- "text": "Text",
- "ttl": 600
}, - {
- "channel": "viber",
- "sender": "fromni",
- "phone": "358000000000",
- "text": "Text",
- "action": {
- "title": "Button",
- "url": "string"
}, - "ttl": 600
}, - {
- "channel": "sms",
- "sender": "fromni",
- "phone": "358000000000",
- "text": "Text",
- "ttl": 172800
}
]
}, - {
- "custom_id": "123",
- "route": [
- {
- "channel": "vk",
- "group": 5965316,
- "phone": "358000000000",
- "text": "Text",
- "ttl": 600
}, - {
- "channel": "viber",
- "sender": "fromni",
- "phone": "358000000000",
- "text": "Text",
- "action": {
- "title": "Button",
- "url": "string"
}, - "ttl": 600
}, - {
- "channel": "sms",
- "sender": "fromni",
- "phone": "358000000000",
- "text": "Text",
- "ttl": 172800
}
]
}
]{- "result": "success",
- "id": [
- "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
- "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
]
}{- "id": "fd698b41-7476-4478-bd1c-d74266f3cc86",
- "custom_id": "123",
- "status": "error",
- "channel": "sms",
- "error": "The text is not matched existing templates",
- "code": 1000
}Possible errors that can occur at the time of Sending a message request.
| Error | Description |
|---|---|
| Not found channel settings | Settings for the channel are not found |
| The channel is not allowed | Channel is not supported for the User |
| The text is not matched existing templates | - |
| No params | - |
| No field "<field name>" | Requied field " |
| Text or image or action must be specified | Applicable for Viber only |
| Incorrect content combination | Applicable for Viber only |
| Action title and URL must be specified | Missed Button text and action URL (Viber only) |
| No phone or user | Missed phone or user (VK channel only) |
| No text or tmpl | Missed text or template (VK channel only) |
To get status reports Status of a message from the platform you should set status report url in the report parameter of your sending request. Status reports are sent to you through a POST request. If you miss the [report] parameter you can always check status reports for your messages from your Account page.
| Status | Description |
|---|---|
| accepted | Message received, preparation for transmission to the operator |
| sent | Message was sent, waiting final status from the Operator |
| unknown | Status unknown |
| rejected | Message is rejected by the Operator |
| undelivered | Message was undelivered |
| expired | Possible delivery time is up |
| deleted | Message was not verified by the Moderator |
| delivered | Message was delivered |
| read | Message was read (where applicable - VK/Viber messages only) |
| error | Sending has failed |
To get error reports from the platform you should set error report url in the report parameter of your sending request. Error reports are sent to you through a POST request. If you miss the [report] parameter you can always check error reports for your messages from your Account page.
| Code | Error | Description |
|---|---|---|
| 1000 | Undocumented mistake (please ask support) | Undocumented mistake (please ask support) |
| 1001 | Internal error | Internal error |
| 1003 | Authorization error | Authorization error |
| 1010 | Tel.number error | Tel.number error |
| 1011 | Sender ID error | Sender ID error |
| 1012 | Message text error | Message text error |
| 1013 | IP error (request from blacklisted IP) | IP error (request from blacklisted IP) |
| 1014 | User message ID error | User message ID error |
| 1015 | Balance error - not enough funds | Balance error - not enough funds |
| 1016 | Delivery failure (routing is not configured) | Delivery failure (routing is not configured) |
| 1018 | You've already sent message with same user message ID | You've already sent message with same user message ID |
| 1019 | Tel.number is in the black list | Tel.number is in the black list |
| 1020 | You've reached max. subscribers per request limit | You've reached max. subscribers per request limit |
| 1021 | Invalid argument | Invalid argument |
| 1022 | Delivery is only opened to the number registered for you account | Delivery is only opened to the number registered for you account |
| 1025 | Wrong sms ID format | Wrong sms ID format |
| 1026 | Wrong user message ID format | Wrong user message ID format |
| 1027 | There should be at least one sms ID in the request | There should be at least one sms ID in the request |
| 1029 | Message with this ID was not found | Message with this ID was not found |
| 1030 | Routing error | Routing error |
| 1031 | Invalid content type | Invalid content type |
| 1033 | Wrong TTL for messengers | Wrong TTL for messengers |
| 1034 | Wrong time-out ("time-to-live") for Viber | Wrong time-out ("time-to-live") for Viber |
| 1035 | Wrong set of parameters for your content (text, image, button) | Wrong set of parameters for your content (text, image, button) |
| 1036 | Wrong image URL | Wrong image URL |
| 1037 | Wrong button URL | Wrong button URL |
| 1040 | Wrong time-out ("time-to-live") for SMS | Wrong time-out ("time-to-live") for SMS |
| 1042 | Missed title for the template | Missed title for the template |
| 1043 | Missed template text | Missed template text |
| 1050 | Template does not exist | Template does not exist |
| 1051 | You don't have access to the template | You don't have access to the template |
| 1052 | There was an error verifying fields values | There was an error verifying fields values |
| 1053 | Missed value that is obligatory | Missed value that is obligatory |
| 1054 | Wrong DATE format | Wrong DATE format |
| 1056 | Wrong value for this field type | Wrong value for this field type |
| 1058 | User can't make that action | User can't make that action |
| 1100 | Unknown error (VK.com) | Unknown error (VK.com) |
| 1101 | Exceeding the limit (VK.com) | Exceeding the limit (VK.com) |
| 1102 | Message delivery is blocked by the VK.com user | Message delivery is blocked by the VK.com user |
| 1200 | No existing transactional messages delivered to the user at the moment (Viber) | No existing transactional messages delivered to the user at the moment (Viber) |
| 1201 | Message delivery is blocked by the Viber user | Message delivery is blocked by the Viber user |
| 1202 | Viber app is not installed | Viber app is not installed |
| 1203 | Old version of Viber app | Old version of Viber app |
Some channels like Viber let you get feedback (replies) from end users. Here you can find the information how to get these replies to you system. End user can send you reply only if your SenderID is registered by Viber with 2-way option. It supports both inbound and outbound messages (please ask Fromni representative if you want to know if your SenderID supports that option or not).
Please set your URL in [reply] parameter when sending a message. So you will get the reply there Reply from an end user.
Returns current balance of your Fromni account.
| Content-Type required | string Example: application/json |
| Authorization required | string Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
{- "result": "success",
- "balance": "500.25"
}Returns your SenderIDs list registered and active for your Account. By using value [all] for the parameter channel you will get all your SenderIDs active for all your delivery channels. By using value [sms], you will get only those SenderIDs that are activated for delivering via SMS.
| Content-Type required | string Example: application/json |
| Authorization required | string Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| channel required | string Enum: "sms" "all" For which channel(s) you need a list of registered SenderID(s) |
{- "channel": "all"
}{- "result": "success",
- "senders": {
- "sms": [
- "fromni"
], - "viber": [
- "fromni"
], - "vk": [
- "fromni_fromni"
]
}
}Verifies and returns phone number in correct format. Checks if the number is mobile and to which country it belongs.
You can use [phone] parameter to get response about one number only. If you need information about multiple phone numbers per request please use [phones] parameter (limit is up to 500 numbers per request). When sending you a report about a phone number its format will be cleared from all the symbols like +()- etc. You will get only figures
| Response parameter | Description |
|---|---|
| phone_source | Phone number (plain figures) |
| phone_number | Phone number on the International standart |
| status | Status report (invalid, ok) |
| country | Country |
| operator | Service provider (Russia only) |
| region_id | Code for the region (Russia only) |
| region_name | Region |
| region_timezone | Timezone difference with Moscow |
| Status | Description |
|---|---|
| invalid | Invalid number / doesn't exist |
| ok | Number is valid and exists |
| Content-Type required | string Example: application/json |
| Authorization required | string Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| phone | string |
| phones | Array of strings |
{- "phone": "358000000000",
- "phones": [
- "358000000000",
- "358000000001"
]
}{- "result": "success",
- "data": [
- {
- "phone_source": "358000000000",
- "phone_number": "358000000000",
- "status": "invalid",
- "country": "FI",
- "operator": "unknown",
- "region_id": "",
- "region_name": "",
- "region_timezone": ""
}, - {
- "phone_source": "358000000001",
- "phone_number": "358000000001",
- "status": "ok",
- "country": "FI",
- "operator": "",
- "region_id": "",
- "region_name": "",
- "region_timezone": ""
}
]
}Returns a list of account templates.
| Content-Type required | string Example: application/json |
| Authorization required | string Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
{- "result": "success",
- "data": {
- "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
- "name": "template name",
- "text": "template text",
- "channel": "sms",
- "group_url": null,
- "status": "approved",
- "comment": "",
- "notify_service": null,
- "active": true,
- "created": 1638306000,
- "updated": 1638306000
}
}Creating a template.
| Content-Type required | string Example: application/json |
| Authorization required | string Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| name | string |
| text required | string |
| channels | Array of strings |
| group_url | string |
| comment | string |
{- "name": "template name",
- "text": "template text",
- "channels": [
- "sms",
- "vk"
], - "group_url": "only VK channel",
- "comment": "comment"
}{- "result": "success",
- "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
- "name": "template name"
}Updating the template.
| Content-Type required | string Example: application/json |
| Authorization required | string Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| id required | string |
required | Array of objects (Template options data) |
{- "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
- "options": {
- "text": "template text",
- "name": "template name",
- "comment": "comment"
}
}{- "result": "success",
- "change": {
- "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
- "name": "template name",
- "text": "template text",
- "channel": "sms",
- "group_url": null,
- "status": "approved",
- "comment": "",
- "notify_service": null,
- "active": true,
- "created": 1638306000,
- "updated": 1638306000
}
}Deleting a template.
| Content-Type required | string Example: application/json |
| Authorization required | string Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| id required | string |
{- "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}{- "result": "success"
}