API Summary

Objects

The API is organized around the following resources:

Objects Description
Account The account object represents a messaging account connected to the oratio platform, e.g. a Facebook Page, a Viber Public Account or a Telegram Bot
Conversation A conversation is unique for each user sending messages to an account.
Message A single text or multimedia message received from a user or sent by an account.
User A user represents a team member on the oratio platform.
Response The response object is used in the response of your integration and consists the message your integration sends to the user.

Account

An account object contains the following fields:

Fields Type Description
id int unique id for the account
provider_id int id of network provider
  • Messenger: 2
  • Telegram: 3
  • Kik: 7
  • Viber: 8
identifier string unique identifier of the messaging network
name string name of the account
connected boolean flag if the account is connected to oratio, always true
team_id int the id of the team it belongs to

Conversation

A conversation object contains the following fields:

Fields Type Description
id int unique id for conversation
account_id int id of the account it belongs to
identifier string unique identifier of the chat of the messaging network
created_at timestamp creation date of the conversation
updated_at timestamp last change made to this conversation
name string (optional) name of the conversation if set
status string current status of the conversation (either "unassigned", "inbox" or "closed").
unassigned = currently no tema member is assigned to this conversation
inbox = assigned to a team member
new = deprecated, now called inbox
closed = conversation was closed by a team member
avatar string (optional) user profile picture if set
auto_respond boolean flag that indicated if an active integration is allowed to respond. true if it's allowed, otherwise response from integration will be ignored
meta object (optional) various meta information from oratio or other integrations about the conversation
blocked boolean true if conversation was blocked/ marked as spam by a team member
human boolean true if it's currently assigned to a human
users Array of User (optional) list of users who are assigned to the conversation

Message

A message object contains the following fields:

Fields Type Description
id int unique id for the message.
account_id int id of account it belongs to.
conversation_id int id of the conversation it belongs to.
sender string indicates who has sent the message (either "subscriber" ot "account").
subscriber - incoming message from the user.
account - outgoing message from an integration or a team member.
messenger_id string identifier of the messaging network
type string type of the message (either text, audio, document, gif, image, video, location)
content string content of the message, string for type text otherwise json object
meta object (optional) various meta information from oratio including the original payload from the messaging network
created_at timestamp creation date of the message
status string status of the message (either "new", "seen" or "automated")
new - indicates a new message which is not seen by a team member.
seen - message has been seen by a team member. Automated answered messages or messages sent by the account will always be "seen" by default
automated - indicates that this message has been handled by an integration.
mime_type string(optional - only set for media messages) the MIME type of the message if determined
user_id int (optional - only set for outgoing messages) user id of the team member who has sent the message, only set for outgoing messages.

User

A user object contains the following fields:

Fields Type Description
id int unique id of the user.
name string name of the user.
email int email of the user.
active boolean true if the user has an active account and access to oratio
created_at timestamp registration date of the user
updated_at timestamp last seen date of the user

Response

The response object consists the actual response your integration sends to the user and has the following fields

Fields Type Description
type string the message type you want to send, currently only text is supported
content object the content object always consists of the message type as key and the actual content as value, e.g. {text: "your message comes here"}

API Reference

Webhook reference

All callbacks that are delivered to your webhook have a common structure. Following fields are part of the callback: account, conversation, message

Example


{
	account: {
		id: 1,
		provider_id: 1,
		identifier: "oratio",
		name: "Team oratio",
		connected: true,
		team_id: 1
	},
	conversation: {
		id: 1,
		account_id: 1,
		identifier: "3x14159265",
		created_at: 1426325195897,
		updated_at: 1426325195897,
		status: "inbox",
		name: "Bruce Wayne",
		avatar: "/path/to/batman.jpg",
		auto_respond: false,
		blocked: false,
		human: true,
		meta: {},
		users: [
			{
				id: 314;
				name: "David",
				email: "david@example.com",
				active: true,
				created_at: 1426325195897,
				updated_at: 1426325195897
			}
		]
	},
	message: {
		id: 1,
		account_id: 1,
		conversation_id: 1,
		sender: "subscriber",
		messenger_id: "1",
		type: "text",
		content:  "Hi",
		meta: {
			raw_json: {},
		},
		created_at: 1426325195897,
		status: "new"
	}
}
				

Send reference

When receiving a callback payload, your integration can decide to answer or pass the conversation on to other integrations. Following fields are part of the response payload: forward, conversation, message, response

Payload

The response object consists for the actual message your integration sends to the user

Fields Type Description
forward boolean This field controls whether the user's message should be forwarded to other Active Integrations connected to this account.
IMPORTANT: Only set this field to false if your integration can respond to the user's message
conversation object (optional) A subset of the conversation object with the fields you want to edit: auto_respond, human, meta
IMPORTANT: Only meta.integrations.your_integration_name key can be modified inside the meta object
message object (optional) A subset of the message object with the fields you want to edit: meta
IMPORTANT: Only meta.integrations.your_integration_name key can be modified inside the meta object
response object (optional) The response object as described above

Examples

A simple text response example.


{
	forward: false,
	conversation: {
		auto_respond: true,
		human: false,
		meta: {
			integrations: {
				your_integration_name: {}
			}
		},
	},
	message: {
		meta: {
			integrations: {
				your_integration_name: {}
			}
		}
	},
	response: {
		type: "text",
		content: {
			text: "Hey 👋! We have successfully sent a message from an integration 🙌"
		}
	}
}
				

If your integration can't find a proper response, you can just forward it to other integrations by setting the forward field to true


{
	forward: true
}
				

You can pass the conversation to a human agent at any time by setting human to true. The auto_respond field controls if integrations still can respond until the conversation is assigned to an agent.


{
	forward: false,
	conversation: {
		auto_respond: false,
		human: true
	}
}