Fromni Bots API

Download OpenAPI specification:Download

API for interacting with the Fromni platform. Mainly designed to run:

  • Campaigns, that means scenarios in which you, i.e. the business, are the initiator of communication. In this case, the response or possible action of the recipient is pre-laid in the scenario.
  • Notifications - you want to send a message to the user and do not expect a response to it. At the same time, the message can be sent, among others, through the WhatsApp Business API.

At its core, the Campaign is a regular chatbot. The only difference is that you write to the User, and he responds to you. Therefore, for the launch of any Campaign, the Script is important (which messages to send, which responses can come, etc.), Channels (through which channels messages are transmitted), Launch conditions (what must happen for the campaign to start). For the convenience of working with the platform, all Scenarios, Channels and Launch Conditions are implemented through the WEB interface. The API also transmits ** Events** that should launch the Campaign, or direct commands to launch the Campaign.

Introduction

Each method is a POST request, which, if successful, returns code 200, and in case of an API error, code 500.

Connection point: https://api.fromni.com/user

Data format: JSON

Encoding: UTF-8

Headers

Authorization: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Content-Type: application/json

Events

Events allow you to launch Campaigns automatically. Events can be created using an API request or via a WEB interface.

Each event that is created has a calculated tag parameter. All events that you create yourself have a "custom" tag.

Transmit Event

When transmitting an event to the system, an attempt will be made to find the Campaign associated with it. If there is one, it will be launched, and its id will be returned in response. It is important that the recipient's phone number is also transmitted in the Event data, and the path to it is defined in the Campaign variables.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
name
required
string

Name of event

data
object

Any object containing event data

Responses

Request samples

Content type
application/json
{
  • "name": "added_to_cart",
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "id": "2c78e241008fedf822288be5"
}

List of available events

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
Schema not provided

Responses

Response samples

Content type
application/json
{
  • "result": "success",
  • "data": [
    ]
}

Campaigns

Campaigns are outgoing communications according to a certain scenario. The scenario must be pre-created in the scenario designer in the WEB interface. There, in particular, the logic of the Campaign is "drawn" and the channels through which messages are sent are connected.

Launch campaign

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
name
string

Campaign name

liveTime
number [ 1 .. 48 ]
Default: 24

The time (in hours) during which the recipient can respond to the campaign

required
Array of objects (Campaign Channels) [ items ]
scenarioId
required
string,

ID of the campaign script that will be launched after the user receives the first message

data
required
Array of objects (CampaignRecipientData) [ items ]

An array of objects with data for each recipient. The object can contain any number of fields, but must have the same structure for each recipient

match
Array of strings

An array of matches of campaign variables and template fields. The header corresponding to the field in which the recipient's phone number is specified ** must be the first.**

Responses

Callbacks

Request samples

Content type
application/json
{
  • "name": "My campaign",
  • "liveTime": 24,
  • "channels": [
    ],
  • "scenarioId": "5eb882228fdef800142e87c2",
  • "data": [
    ],
  • "match": [
    ]
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "id": "2c78e241008fedf822288be5"
}

Callback payload samples

Callback
POST: The campaign is completed
Content type
application/json
{
  • "name": "campaign_completed",
  • "data": {
    }
}

List of campaigns sent

Returns a list of Campaigns that were launched during the specified period. The method can be useful for estimating the number of campaigns sent in a certain period and getting detailed statistics for a specific Campaign.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
startDate
string

Beginning of the period

endDate
string

End of the period

type
string or null
Enum: "event" "manual"

Campaign type ("event" - campaigns by event, "manual" - campaigns launched directly)

Responses

Request samples

Content type
application/json
{
  • "startDate": "2021-01-21T00:00:00:000Z",
  • "endDate": "2021-02-21T00:00:00:000Z\"",
  • "type": "event"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "data": [
    ]
}

Campaign statistics

Unlike returning statistics to the Callback server, this method allows you to get the current statistics for the campaign yourself, even if it is not completed. Returns all parameters of the launched campaign, as well as the modified list of recipients in the docs field.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
id
required
string

Campaign ID

Responses

Request samples

Content type
application/json
{
  • "id": "2c78e241008fedf822288be5"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "id": "2c78e241008fedf822288be5",
  • "name": "My campaign",
  • "liveTime": 48,
  • "channels": [
    ],
  • "scenarioId": "5eb882228fdef800142e87c2",
  • "templateId": 1,
  • "docs": [
    ],
  • "match": [
    ],
  • "headers": [
    ],
  • "createdAt": "2020-10-20T00:00:00.436Z"
}

Notifications

Notifications - the ability to send users a one-way message using most of the available channels. As part of this solution, you send a specific message. The task of the platform is to deliver this message. At the same time, if a template is found for a message in your account, the message will automatically leave by those channels for which the found template was registered/approved. This is how message delivery can be organized, for example, through the WhatsApp Business API. If the templates are not detected, the message is automatically forwarded via SMS (it is necessary that this channel is connected in the account).

Send notification

If the channels and smsConnectionId parameters are not specified, the notification will be sent in accordance with the specified settings in the account.

Sending is possible by phone number or by contact ID. In any case, an attempt will be made first to find the user's digital profile in Fromni. Then, using the available identifiers in various messengers, an attempt will be made to deliver the notification to the specified channels (until the 1st successful sending).

Some channels allow attaching attachments (in Instagram and Viber - business messages only 1 image is allowed; Notify and SMS cannot contain attachments).

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
Any of
phone
required
string

Recipient's number

contactId
string

If phone is not specified, then the subscriber id in the Fromni system (note that the subscriber must have a known phone number)

required
object
Array of objects (Campaign Channels) [ items ]
smsConnectionId
number

ID of the connection to the SMS channel through which the notification should be sent, if it could not be done through the specified channels

Responses

Callbacks

Request samples

Content type
application/json
{
  • "phone": 79000000000,
  • "contactId": "5f3cd834e8aadd00137359aa",
  • "message": {},
  • "channels": [
    ],
  • "smsConnectionId": 5
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "id": "6062fdc861914f0013e793a2"
}

Callback payload samples

Callback
POST: Notification Status Updated
Content type
application/json
{
  • "name": "notification_message_updated",
  • "data": {
    }
}

Media Storage

Media storage allows you to upload files to get a direct link to them, which can be specified for attachment when sending a message. Attachments from users' incoming messages are also stored in the storage.

The file size is currently limited to 10 MB.

Get the server parameters to download

To upload a file to the storage, you first need to get the server parameters to upload. The response contains the url field to which you need to send a POST request with a body in the FromData format, the link is valid for 1 hour. For each new uploaded element, you need to get new parameters.

The response also contains a fields object, each key of which must be passed in its original form together with the request as a key-value pair in FormData. The file itself is transmitted by the file key and must be specified most recently. The response returns the mediaUrl field containing a direct link to the future uploaded file, use it to insert it into the message.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
filename
required
string

The file name must have the extension

Responses

Request samples

Content type
application/json
{
  • "filename": "image.png"
}

Response samples

Content type
application/json
{}

Messenger

The section describes the methods of direct communication with live operators. The mechanism is triggered at the moment when a type of incoming message is received from the User, which according to the Scenario should be processed by a specialist on the Customer's side and through the Customer's information system. Information about the incoming message will be sent to the Callback server (request type - * A new dialog with the operator in the Messenger* has been initiated). Next, you can request the dialog message history using the Dialog Messages method.

A new dialog with the operator has been initiated Webhook

The data object contains basic information about the dialog.

The contact field contains known contact identifiers in various messengers (phone, vkId, instagramId, etc.). The connection field contains information about the connection within which the dialogue was initiated, including the channel identifier (vk, whatsapp-business, fb, viber, etc.)

Request Body schema: application/json
name
required
string
required
object (Dialog)

Responses

Request samples

Content type
application/json
{
  • "name": "conversation_operator_requested",
  • "data": {
    }
}

A new message has been received from the user within an open dialog Webhook

Request Body schema: application/json
name
required
string
required
object

Responses

Request samples

Content type
application/json
{
  • "name": "conversation_message_created",
  • "data": {
    }
}

List of dialogs

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
offset
number
Default: 0

Indent from the beginning of the list

limit
number
Default: 10

Maximum number of entries in the answer

Responses

Request samples

Content type
application/json
{
  • "offset": 0,
  • "limit": 10
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "data": [
    ]
}

Dialog Messages

The method can be useful to load the User's communication history with the Bot after the operator is connected to the dialog.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
conversationId
string

Dialog ID

Responses

Request samples

Content type
application/json
{
  • "conversationId": "5f3cd834e8aadd00137359aa"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "data": [
    ]
}

Send a message to the dialog

The operator can send a message to the dialog only if the dialog's operatorMode has not expired.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
conversationId
string

Dialog ID

object

Responses

Callbacks

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "result": "success",
  • "messageId": 2,
  • "status": "sent",
  • "conversationId": "5f3cd834e8aadd00137359aa"
}

Callback payload samples

Callback
POST: The status of the message sent to the user via Messenger has been updated
Content type
application/json
{
  • "name": "conversation_message_updated",
  • "data": {