Skip to main content
API docs by Redocly

Texting API (1.0.0-beta2)

Download OpenAPI specification:Download

Campaign SMS webhook Webhook

This webhook is triggered by campaign SMS activity: when a campaign sends out messages to students or when someone replies. JSON payload specified below is sent to the custom URI specified in "Ocelot SMS Webhook" integration settings in the Admin portal.

This event notifies of both outbound and inbound SMS. For outbound messages, delivery status is also supplied, while inbound are simply registered as they are received. Since campaigns usually generate a lot of traffic, events are batched over fixed time intervals.

Request Body schema: application/json
required
Array
One of
eventId
string <uuid> (EventId)

Unique event identifier.

if Ocelot re-sends the event payload due to an error response, retries will use the same event Uuid.

Array of objects (SmsWebhookContactField)

Array of contact fields (e.g. phone number, email, first name, etc)

triggerType
string
Value: "inbound"

Webhook trigger type

dateTime
string <date-time>

Date and time of the event in ISO 8601 format

campaignId
string

Unique campaign identifier in Ocelot system

message
string (PlainMessage) <= 2000

Plain text to be sent to recipient.

name
string
Value: "IncomingSms.received"

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Global Opt In/Out webhook Webhook

This webhook is triggered by contact opt-in or opt-out activity.

JSON payload specified below is sent to the custom URI specified in "Global Opt In/Out Webhook" integration settings in the Admin portal.

Request Body schema: application/json
required
One of
eventId
string <uuid> (EventId)

Unique event identifier.

if Ocelot re-sends the event payload due to an error response, retries will use the same event Uuid.

object (PhoneNumberContactField)

The contact field used as identifier in the both systems.

dateTime
string <date-time>

Date and time of the event in ISO 8601 format

name
string
Value: "PhoneNumber.optedIn"

Responses

Request samples

Content type
application/json
Example
{
  • "eventId": "d6703cc8-9e79-415d-ac03-a4dc7f6ab43c",
  • "referenceField": {
    },
  • "dateTime": "2019-08-24T14:15:22Z",
  • "name": "PhoneNumber.optedIn"
}

Get 1:1 phone numbers

Gets a list of resuable phone numbers eligible for 1:1 conversations that are available for a given operator.

Request Body schema: application/json
required
operator
required
email

The email address of the operator

skip
number

Pagination settings - number of records to skip

limit
number

Pagination settings - number of records to return

orderBy
string
Enum: "chatbotId" "campusId" "officeId" "label" "description"

Field to order records by

order
string
Enum: "ASC" "DESC"

Sorting order on "orderBy" field

Responses

Request samples

Content type
application/json
{
  • "operator": "jon.smith@yourdoamin.com",
  • "skip": 0,
  • "limit": 10,
  • "orderBy": "chatbotId",
  • "order": "ASC"
}

Response samples

Content type
application/json
{
  • "total": 10,
  • "skip": 0,
  • "limit": 10,
  • "data": [
    ]
}

Get transcripts

Returns a transcript of all conversation turns that are available for a given operator and filters by phone number

Request Body schema: application/json
required
operator
required
email

The email address of the operator

phoneNumber
required
string

The phone number of either campaign or contact

skip
number

Pagination settings - number of records to skip

limit
number

Pagination settings - number of records to return

orderBy
string
Enum: "from" "to" "senderType" "timestamp"

Field to order records by

order
string
Enum: "ASC" "DESC"

Sorting order on "orderBy" field

Responses

Request samples

Content type
application/json
{
  • "operator": "john.doe@example.com",
  • "phoneNumber": "123-456-7890",
  • "skip": 0,
  • "limit": 10,
  • "orderBy": "from",
  • "order": "ASC"
}

Response samples

Content type
application/json
{
  • "total": 10,
  • "skip": 0,
  • "limit": 10,
  • "data": [
    ]
}

Send 1:1 SMS

Send 1:1 sms

Request Body schema: application/json
required
from
required
string (ProvisionedPhoneNumber)

Pre-provisioned phone number (in admin UI)

operator
required
email

The email address of the operator to be assigned to conversation

required
Array of objects (SmsApiInputItem) <= 100 items
smsWebhookUri
string

If set, overrides the default SMS webhook/callback URI (specified in Ocelot API config)

Callbacks

Request samples

Content type
application/json
{
  • "from": "123-456-7890",
  • "operator": "jon.smith@yourdoamin.com",
  • "messages": [
    ],
  • "smsWebhookUri": "https://your.domain.example/your/webhook/uri/path"
}

Callback payload samples

Callback
POST: SMS webhook URL
Content type
application/json
[
  • {
    }
]

Send 1:1 SMS (legacy) Deprecated

Deprecated, an alias of texting/1-1/send endpoint (see above).