SaySimple Message Intelligence API (1.0.0)

Download OpenAPI specification:Download

The SaySimple Messaging Intelligence API - 'Intelligence API' in short - allow you to interact with the analytical part of SaySimple. Insert data and receive metrics.

Global aggreements

  1. Dates are in ISO8601 preferably in UTC.
    Examples:

    • 2020-01-15T15:00:39Z
    • 2019-10-08T15:00:21+01:00 is correct, but we'd rather receive it in UTC timezone, so we are conscious about time.
    • 2020-01-15 01:12:41 is not correct because it is missing the T between the date and the time.
  2. Data should be as 'raw' as possible. Providing as much data as possible will help in creating more high-end metrics. We'll take care of obfuscate of the data where needed. Having questions about data retention, GDPR or our security measurements, please contact us!

How to read the documentation

We hope this documenation makes our API as clear as needed for your development process. But we are happy to assist you in any way we can during development - up to certain extends of course 😉. Please contact us at support@saysimple.com

In this table you can find the value corresponding with the variables.

Variable Value
apiEndpoint https://api.saysimple.io/insights/v1
documentationEndpoint https://api.saysimple.io/docs/intelligence

SDKs

Right now we offer only a JavaScript SDK. But please do let us know if you are missing an SDK for your tech stack! Just drop us an email at support@saysimple.nl.

JavaScript / Node.js

Please see the readme of the NPM Package for installation and usage. This documentation will provide code samples for the SDK.

Authentication

OAuth

The Saysimple API is (obviously) protected for unauthorized usage.

Schematic example

CLIENT  +------------Authenticate-----------> SAYSIMPLE
                 (identifier + secret)            |
                                                  |
  +------------------Access Token-----------------+
  |                    (as JWT)
  |
  +--------------------Request--------------------+
        (Authorization: Bearer [Access Token])    |
                                                  |
  <-------------------Response--------------------+

See /authenticate for the implementation details and examples

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: https://api.saysimple.io/messaging/v1/auth/authenticate
Refresh URL: Not yet implemented
Scopes:
  • api_credentials -

    Retrieve an access token

Errors

The API uses standard HTTP status codes extended with custom error codes.

Every error has a code, a message and a link to a page with more info for that specific error. Some errors will use just the default HTTP status code. For example a 404, this HTTP status code is self-explanatory. This will result in a response like this:

// RESPONSE CODE
404 - Not Found

// RESPONSE PAYLOAD
{
  "code": 404,
  "message": "Resource not found",
  "moreInfo": "{documentationEndpoint}/errors/404"
}

Here you see the HTTP status code matches the code in the response payload.

However if you, for example made a type in your request parameter the appropriate HTTP status code could be 400. This could mean still a lot of things. The response payload will give you more in-depth info about it.

// RESPONSE CODE
400 - Bad Request

// RESPONSE PAYLOAD
{
  "code": 1536,
  "message": "Malformed query parameters",
  "moreInfo": "{documentationEndpoint}/errors/1536?fields[between]=Date%20is%20not%20formated%20as%20ISO8601&fields[channel]=Channel%20should%20be%20a%20string"
}

Now you see the code doesn't match the HTTP status code. Also the message is kind of generic. But if you follow the URL you'll go to a page with an explaination of the errors and how you can fix them.

Versioning

We try to expand a running version with new functionalities without breaking your code. Sometimes we need to create a new version. We will communicate this new version as soon as possible giving you all the time needed to move to the new version.

Older versions will be supported for some time before being terminated.

Current stable version 1.0.0

Messages

Adding messages to the data pool. Reading metrics from that pool.

A message is a single piece of content (with our withour multiple media) to communicate with another party. A message can be send and received only to or by one person.

Add A Message

Add a message to the statistics. Not all fields are mandatory, but it is good practise to provide as many details as possible, which will return in more higher quality statistics.

Note: To get accurate median and average statistics for first reply time you will need to add the tag: "system:automatic_reply" to the message for automatic replies. This will prevent counting automatic replies as the first reply time.

Authorizations:
OAuth (api_credentials)
Request Body schema: application/json
tenant
required
string

This is the identifier of the tenant. This should match the one you've been given by SaySimple. Based on your access token / secret you will be given access to perform actions on behalf of this user.

direction
required
string
Enum: "IN" "OUT"

The direction of the message. IN for receiving, OUT means sending.

channel
required
string (Channel) [A-Z_]{2,30}

The channel where the message is send over. You are free to use any identifier as long as it only uses uppercase letters (A-Z) with a minimum length of 2 and a maximum length of 30. Please take care of setting the right key for your channel name, since this is not changeable afterwards.

tenantChannelIdentifier
required
string (Identifier) <= 100 characters

A unique identifier to reach the tenant or the customer over a channel. Could be a phone number for SMS or WhatsApp, or the Facebook Messenger ID for Facebook Messenger.

customerChannelIdentifier
required
string (Identifier) <= 100 characters

A unique identifier to reach the tenant or the customer over a channel. Could be a phone number for SMS or WhatsApp, or the Facebook Messenger ID for Facebook Messenger.

required
object

The Message object should contain the actual message, but it is also possible to add extra meta data. This data is not rendered in a chart yet, but by providing the data we could generate charts for this type of data later on and use this 'historical' data.

time
string <ISO-8601>
Default: "NOW"

DateTime in ISO-8601 (preferrably in UTC)

provider
required
string (Messaging Provider) [A-Z_]{2,100}

The provider providing the messaging channel. Could be Facebook, Twilio, CM, Sunshine, SaySimple or any other. You are free to use any identifier as long as it only uses uppercase letters (A-Z) with a minimum length of 2 and a maximum length of 30. Please take care of setting the right key for your channel name, since this is not changeable afterwards.

agent
string (Customer Care Agent) <= 100 characters

The identifier of the customer care agent who handles this messages. Based on the direction property this could be the sender or the recipient. This identifier is a string and is the identifier of the agent, an email address for example.

tags
object (Tag Name)

A tag identifies one or multiple topic(s) for a conversation.

We define three types of tags. User tags, team tags and system tags. User tags are free form and can categorize the message. For example a message send by somebody famous with a question about their invoice could be tagged with 'VIP' and 'Finance'. To add these as tags you need to prefix them with user:. In this case we'd add user:VIP and user:Finance.

Team tags are used for linking a team to a message. You can only link one team per message. Multiple teams wont work, as it will only select the first added team. To add a team as a tag you need to prefix them with team:. In this particular case we'd add team:Sales.

System tags are reserved for certain metadata to create valuable metrics of these messages. Right now we have the following system tags defined:

Tag Description
system:paid_template A paid (WhatsApp) template is sent. This will occur if the customer care agent sends a message outside the customer care window (24h) Facebook defined
system:free_template The message sent was a template, but it was sent without any additional costs
conversation
string (Conversation) <= 100 characters

A unique identifier which refers to a conversation. Could be an auto incremented identifier, GUID or any other unique alphanumeric reference.

businessHours
object (Business Hours)

The business hours define what business hours are set for the channel when adding a message. These are used when calculating different statistics that are depedent of business hours.

The object starts with a 0, that indicates Sunday, increasing to 6 that indicates Saturday.

timeZone
string

A string indicating a time zone

Responses

Request samples

Content type
application/json
Example
{
  • "tenant": "teddies",
  • "direction": "OUT",
  • "time": "2020-02-14T12:03:59Z",
  • "provider": "SAYSIMPLE",
  • "channel": "SMS",
  • "tenantChannelIdentifier": "+31612345678",
  • "customerChannelIdentifier": "+31687654321",
  • "agent": "teddy_himself@teddies.com",
  • "message": {
    },
  • "conversation": "42",
  • "businessHours": {
    },
  • "timeZone": "UTC"
}

Response samples

Content type
application/json
""

Total Messages Summed

Getting the sum of messages send and received.

Authorizations:
OAuth (api_credentials)
query Parameters
between
string <DateTime ISO8601>
Default: "30 days ago"

Optional
Data is fetched between two dates. This is the from or start date. Format is ISO8601.

and
string <DateTime ISO8601>
Default: "30 days after BETWEEN parameter"

Optional
Data is fetched between two dates. This is the to or end date. Format is ISO8601.

direction
string
Default: "ALL"
Enum: "IN" "OUT" "ALL"

Optional
Get the data for only received (IN) or send (OUT) messages. Or receive send and received (ALL).

agent
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple agent(s). Make sure to urlencode the value.

channel
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more channels (ie. 'WHATSAPP', 'FACEBOOK_MESSENGER').

tag
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple tag(s). Make sure to urlencode the value.

provider
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more providers (ie. TWILIO, SMOOCH).

identifier
Array of strings
Default: "*"

Optional
Get the statistics for one or more identities (ie. phone numbers, facebook messenger ids). Make sure to urlencode the value.

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getMessagesSummed();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
{
  • "aggregatedBy": "DAY",
  • "firstDataOccurrence": "2020-06-01T00:00:00.000Z",
  • "lastDataOccurrence": "2020-06-10T00:00:00.000Z",
  • "data": {
    },
  • "aggregatedValue": 200634,
  • "previousAggregatedValue": 100061
}

Total Paid Templates Sent

Getting the sum of messages sent as a paid template

Authorizations:
OAuth (api_credentials)
query Parameters
between
string <DateTime ISO8601>
Default: "30 days ago"

Optional
Data is fetched between two dates. This is the from or start date. Format is ISO8601.

and
string <DateTime ISO8601>
Default: "30 days after BETWEEN parameter"

Optional
Data is fetched between two dates. This is the to or end date. Format is ISO8601.

agent
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple agent(s). Make sure to urlencode the value.

channel
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more channels (ie. 'WHATSAPP', 'FACEBOOK_MESSENGER').

tag
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple tag(s). Make sure to urlencode the value.

provider
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more providers (ie. TWILIO, SMOOCH).

identifier
Array of strings
Default: "*"

Optional
Get the statistics for one or more identities (ie. phone numbers, facebook messenger ids). Make sure to urlencode the value.

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getSentPaidTemplates();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
{
  • "aggregatedBy": "DAY",
  • "firstDataOccurrence": "2020-06-01T00:00:00.000Z",
  • "lastDataOccurrence": "2020-06-10T00:00:00.000Z",
  • "data": {
    },
  • "aggregatedValue": 200634,
  • "previousAggregatedValue": 100061
}

Message Distribution

Getting the distribution of messages.

Data is grouped by different periods depending on the dates given:

Period Group by
Greater than 4 years YEAR
Greater than 2 years and less than 4 years QUARTER
Greater than 31 days and less than 2 years MONTH
Greater than 14 days and less than 31 days WEEK
Greater than 1 day and less than 14 days DAY
Less than 1 day HOUR
Authorizations:
OAuth (api_credentials)
query Parameters
between
string <DateTime ISO8601>
Default: "30 days ago"

Optional
Data is fetched between two dates. This is the from or start date. Format is ISO8601.

and
string <DateTime ISO8601>
Default: "30 days after BETWEEN parameter"

Optional
Data is fetched between two dates. This is the to or end date. Format is ISO8601.

direction
string
Default: "ALL"
Enum: "IN" "OUT" "ALL"

Optional
Get the data for only received (IN) or send (OUT) messages. Or receive send and received (ALL).

agent
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple agent(s). Make sure to urlencode the value.

channel
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more channels (ie. 'WHATSAPP', 'FACEBOOK_MESSENGER').

tag
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple tag(s). Make sure to urlencode the value.

provider
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more providers (ie. TWILIO, SMOOCH).

identifier
Array of strings
Default: "*"

Optional
Get the statistics for one or more identities (ie. phone numbers, facebook messenger ids). Make sure to urlencode the value.

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getMessageDistribution();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
{
  • "aggregatedBy": "DAY",
  • "firstDataOccurrence": "2020-06-01T00:00:00.000Z",
  • "lastDataOccurrence": "2020-06-10T00:00:00.000Z",
  • "data": {
    },
  • "aggregatedValue": 200634,
  • "previousAggregatedValue": 100061
}

Response Times (Average)

Getting the average time between messages.

By default you get the average response/wait time between messages. You can retrieve the average response time of agents or contacts by using the direction parameter. Use "OUT" for average response time of agents and "IN" for average response time of contacts.

Data is grouped by different periods depending on the dates given:

Period Grouped by
Greater than 5 years YEAR
Greater than 2 years and less than 5 years QUARTER
Greater than 1 year and less than 2 years MONTH
Greater than 31 days and less than 1 year WEEK
Greater than 2 day and less than 31 days DAY
Less than 1 day HOUR
Authorizations:
OAuth (api_credentials)
query Parameters
between
string <DateTime ISO8601>
Default: "30 days ago"

Optional
Data is fetched between two dates. This is the from or start date. Format is ISO8601.

and
string <DateTime ISO8601>
Default: "30 days after BETWEEN parameter"

Optional
Data is fetched between two dates. This is the to or end date. Format is ISO8601.

agent
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple agent(s). Make sure to urlencode the value.

channel
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more channels (ie. 'WHATSAPP', 'FACEBOOK_MESSENGER').

tag
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple tag(s). Make sure to urlencode the value.

provider
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more providers (ie. TWILIO, SMOOCH).

identifier
Array of strings
Default: "*"

Optional
Get the statistics for one or more identities (ie. phone numbers, facebook messenger ids). Make sure to urlencode the value.

direction
string
Default: "ALL"
Enum: "IN" "OUT" "ALL"

Optional
Get the data for only received (IN) or send (OUT) messages. Or receive send and received (ALL).

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getMessagesResponseTimesAverage();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
{
  • "aggregatedBy": "HOUR",
  • "firstDataOccurrence": "2020-06-01T00:00:00.000Z",
  • "lastDataOccurrence": "2020-06-01T13:00:00.000Z",
  • "data": {
    },
  • "aggregatedValue": 1200,
  • "previousAggregatedValue": 1600
}

Active Contacts

Getting the metrics on contacts.

A contact is someone who contacted the tenant via a channel (whatsapp for example). If a tenant has multiple identifiers on one channel (three whatsapp numbers for example) and the customer sends a message to all identifiers this would count as three contacts.

Example Frank wants to contact the customer service of Teddies Inc. Teddies exposes two Whatsapp numbers on their website. One general number and one for questions about orders. Frank sends his message regarding his order to the general number. This is counted as one active contact for this moment. A second later Frank notices the other number and sends a message to the special order number as well. Although it is still Frank we'll count two active contacts. If Frank is really desperate to get in contact with the customer care and he'd also sends a message via Twitter DM to Teddies Inc. this will be counted as a third active contact. And so forth.

Total Active Contacts

This metric shows the sum of Active Contacts in a certain period.

Authorizations:
OAuth (api_credentials)
query Parameters
between
string <DateTime ISO8601>
Default: "30 days ago"

Optional
Data is fetched between two dates. This is the from or start date. Format is ISO8601.

and
string <DateTime ISO8601>
Default: "30 days after BETWEEN parameter"

Optional
Data is fetched between two dates. This is the to or end date. Format is ISO8601.

agent
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple agent(s). Make sure to urlencode the value.

channel
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more channels (ie. 'WHATSAPP', 'FACEBOOK_MESSENGER').

tag
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple tag(s). Make sure to urlencode the value.

provider
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more providers (ie. TWILIO, SMOOCH).

identifier
Array of strings
Default: "*"

Optional
Get the statistics for one or more identities (ie. phone numbers, facebook messenger ids). Make sure to urlencode the value.

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getActiveContactsSummed();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
{
  • "aggregatedBy": "DAY",
  • "firstDataOccurrence": "2020-06-01T00:00:00.000Z",
  • "lastDataOccurrence": "2020-06-10T00:00:00.000Z",
  • "data": {
    },
  • "aggregatedValue": 1981,
  • "previousAggregatedValue": 1468
}

Active Contacts Ditributions

This metric shows the distribution of the active contacts by country. It will show the top 10 countries with the most active contacts

Authorizations:
OAuth (api_credentials)
query Parameters
between
string <DateTime ISO8601>
Default: "30 days ago"

Optional
Data is fetched between two dates. This is the from or start date. Format is ISO8601.

and
string <DateTime ISO8601>
Default: "30 days after BETWEEN parameter"

Optional
Data is fetched between two dates. This is the to or end date. Format is ISO8601.

agent
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple agent(s). Make sure to urlencode the value.

channel
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more channels (ie. 'WHATSAPP', 'FACEBOOK_MESSENGER').

tag
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple tag(s). Make sure to urlencode the value.

provider
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more providers (ie. TWILIO, SMOOCH).

identifier
Array of strings
Default: "*"

Optional
Get the statistics for one or more identities (ie. phone numbers, facebook messenger ids). Make sure to urlencode the value.

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getActiveContactsDistributions();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
{
  • "aggregatedBy": "DAY",
  • "firstDataOccurrence": "2020-06-01T00:00:00.000Z",
  • "lastDataOccurrence": "2020-06-10T00:00:00.000Z",
  • "data": {
    }
}

Agents

An agent is an employee working at the customer service. They will send messages to customers.

Agents are created automatically upon sending a message (see 'Add Message'). The agent field is a string field, so the values you'll receive on this endpoint could be names, email addresses phone numbers or any other identifier you've set up.

List all agents

Getting a list of all agents who have been using the platform now and in the past.

Authorizations:
OAuth (api_credentials)

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getAgents();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
[
  • "agent_for@teddies.co.uk",
  • "manager@teddies.co.uk"
]

Channels

A channel is a combination of a channel name and identifier.

Channel name
The channel the message is send over. An example of this could be: "WHATSAPP", "SMS" or "FACEBOOK_MESSANGER".

Channel identifier
A unique identifier to reach the tenant or the customer over a channel. Could be a phone number for SMS or WhatsApp, or the Facebook Messenger ID for Facebook Messenger.

List all channels and channel identifiers

Getting a list of objects containing channel and tenant channel identifiers whom have been used on the platform now and in the past.

Authorizations:
OAuth (api_credentials)

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getChannels();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Conversations

A conversation is a collection of all messages that share the same conversation identifier

A conversation is created automatically upon sending a message with a unique conversation identifier (see 'Add Message'). Once a conversation is created subsequent messages with the same conversation identifier are grouped under that conversation.

First Reply Times (Median)

Getting the median of the first reply time.

The first reply time is the time it took an agent for responding the first time in a conversation with a customer.

Data is grouped by different periods depending on the dates given:

Period Group by
Greater than 5 years YEAR
Greater than 2 years and less than 5 years QUARTER
Greater than 1 year and less than 2 years MONTH
Greater than 31 days and less than 1 year WEEK
Greater than 2 day and less than 31 days DAY
Less than 1 day HOUR
Authorizations:
OAuth (api_credentials)
query Parameters
between
string <DateTime ISO8601>
Default: "30 days ago"

Optional
Data is fetched between two dates. This is the from or start date. Format is ISO8601.

and
string <DateTime ISO8601>
Default: "30 days after BETWEEN parameter"

Optional
Data is fetched between two dates. This is the to or end date. Format is ISO8601.

agent
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple agent(s). Make sure to urlencode the value.

channel
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more channels (ie. 'WHATSAPP', 'FACEBOOK_MESSENGER').

tag
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple tag(s). Make sure to urlencode the value.

provider
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more providers (ie. TWILIO, SMOOCH).

identifier
Array of strings
Default: "*"

Optional
Get the statistics for one or more identities (ie. phone numbers, facebook messenger ids). Make sure to urlencode the value.

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getConversationsFirstReplyTimesMedian();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
{
  • "aggregatedBy": "DAY",
  • "firstDataOccurrence": "2020-06-01T00:00:00.000Z",
  • "lastDataOccurrence": "2020-08-13T00:00:00.000Z",
  • "data": {
    },
  • "aggregatedValue": 8005,
  • "previousAggregatedValue": 10546
}

First Reply Times (Average)

Getting the average of the first reply time.

The first reply time is the time it took an agent for responding the first time in a conversation with a customer.

Data is grouped by different periods depending on the dates given:

Period Group by
Greater than 5 years YEAR
Greater than 2 years and less than 5 years QUARTER
Greater than 1 year and less than 2 years MONTH
Greater than 31 days and less than 1 year WEEK
Greater than 2 day and less than 31 days DAY
Less than 1 day HOUR
Authorizations:
OAuth (api_credentials)
query Parameters
between
string <DateTime ISO8601>
Default: "30 days ago"

Optional
Data is fetched between two dates. This is the from or start date. Format is ISO8601.

and
string <DateTime ISO8601>
Default: "30 days after BETWEEN parameter"

Optional
Data is fetched between two dates. This is the to or end date. Format is ISO8601.

agent
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple agent(s). Make sure to urlencode the value.

channel
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more channels (ie. 'WHATSAPP', 'FACEBOOK_MESSENGER').

tag
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple tag(s). Make sure to urlencode the value.

provider
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more providers (ie. TWILIO, SMOOCH).

identifier
Array of strings
Default: "*"

Optional
Get the statistics for one or more identities (ie. phone numbers, facebook messenger ids). Make sure to urlencode the value.

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getConversationsFirstReplyTimesAverage();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
{
  • "aggregatedBy": "DAY",
  • "firstDataOccurrence": "2020-06-01T00:00:00.000Z",
  • "lastDataOccurrence": "2020-08-13T00:00:00.000Z",
  • "data": {
    },
  • "aggregatedValue": 8005,
  • "previousAggregatedValue": 10546
}

First Reply Times During Business Hours (Median)

Getting the median of the first reply time during business hours.

The first reply time during business is the time it took an agent for responding the first time in a conversation with a customer during business hours. For example: a customer sends a message at 16:55:00, while the business hours states that they open at 08:00:00 and close at 17:00:00. When the agent reponds the next day at 08:05:00, the time that is calculated will be 10 minutes, as that is the time it took during the business hours to respond.

Data is grouped by different periods depending on the dates given:

Period Group by
Greater than 5 years YEAR
Greater than 2 years and less than 5 years QUARTER
Greater than 1 year and less than 2 years MONTH
Greater than 31 days and less than 1 year WEEK
Greater than 2 day and less than 31 days DAY
Less than 1 day HOUR
Authorizations:
OAuth (api_credentials)
query Parameters
between
string <DateTime ISO8601>
Default: "30 days ago"

Optional
Data is fetched between two dates. This is the from or start date. Format is ISO8601.

and
string <DateTime ISO8601>
Default: "30 days after BETWEEN parameter"

Optional
Data is fetched between two dates. This is the to or end date. Format is ISO8601.

agent
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple agent(s). Make sure to urlencode the value.

channel
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more channels (ie. 'WHATSAPP', 'FACEBOOK_MESSENGER').

tag
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple tag(s). Make sure to urlencode the value.

provider
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more providers (ie. TWILIO, SMOOCH).

identifier
Array of strings
Default: "*"

Optional
Get the statistics for one or more identities (ie. phone numbers, facebook messenger ids). Make sure to urlencode the value.

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getConversationsFirstReplyTimesBusinessHoursMedian();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
{
  • "aggregatedBy": "DAY",
  • "firstDataOccurrence": "2020-06-01T00:00:00.000Z",
  • "lastDataOccurrence": "2020-08-13T00:00:00.000Z",
  • "data": {
    },
  • "aggregatedValue": 8005,
  • "previousAggregatedValue": 10546
}

First Reply Times During Business Hours (Average)

Getting the average of the first reply time during business hours.

The first reply time during business is the time it took an agent for responding the first time in a conversation with a customer during business hours. For example: a customer sends a message at 16:55:00, while the business hours states that they open at 08:00:00 and close at 17:00:00. When the agent reponds the next day at 08:05:00, the time that is calculated will be 10 minutes, as that is the time it took during the business hours to respond.

Data is grouped by different periods depending on the dates given:

Period Group by
Greater than 5 years YEAR
Greater than 2 years and less than 5 years QUARTER
Greater than 1 year and less than 2 years MONTH
Greater than 31 days and less than 1 year WEEK
Greater than 2 day and less than 31 days DAY
Less than 1 day HOUR
Authorizations:
OAuth (api_credentials)
query Parameters
between
string <DateTime ISO8601>
Default: "30 days ago"

Optional
Data is fetched between two dates. This is the from or start date. Format is ISO8601.

and
string <DateTime ISO8601>
Default: "30 days after BETWEEN parameter"

Optional
Data is fetched between two dates. This is the to or end date. Format is ISO8601.

agent
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple agent(s). Make sure to urlencode the value.

channel
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more channels (ie. 'WHATSAPP', 'FACEBOOK_MESSENGER').

tag
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple tag(s). Make sure to urlencode the value.

provider
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more providers (ie. TWILIO, SMOOCH).

identifier
Array of strings
Default: "*"

Optional
Get the statistics for one or more identities (ie. phone numbers, facebook messenger ids). Make sure to urlencode the value.

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getConversationsFirstReplyTimesBusinessHoursAverage();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
{
  • "aggregatedBy": "DAY",
  • "firstDataOccurrence": "2020-06-01T00:00:00.000Z",
  • "lastDataOccurrence": "2020-08-13T00:00:00.000Z",
  • "data": {
    },
  • "aggregatedValue": 8005,
  • "previousAggregatedValue": 10546
}

Total Resolved Conversations

This metric shows the amount of resolved conversations in a certain period.

Resolved conversations are conversations with the status "resolved". To resolve conversations trigger the resolve conversations event.

Authorizations:
OAuth (api_credentials)
query Parameters
between
string <DateTime ISO8601>
Default: "30 days ago"

Optional
Data is fetched between two dates. This is the from or start date. Format is ISO8601.

and
string <DateTime ISO8601>
Default: "30 days after BETWEEN parameter"

Optional
Data is fetched between two dates. This is the to or end date. Format is ISO8601.

agent
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple agent(s). Make sure to urlencode the value.

channel
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more channels (ie. 'WHATSAPP', 'FACEBOOK_MESSENGER').

tag
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple tag(s). Make sure to urlencode the value.

provider
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more providers (ie. TWILIO, SMOOCH).

identifier
Array of strings
Default: "*"

Optional
Get the statistics for one or more identities (ie. phone numbers, facebook messenger ids). Make sure to urlencode the value.

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getConversationsResolved();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
{
  • "aggregatedBy": "DAY",
  • "firstDataOccurrence": "2020-06-01T00:00:00.000Z",
  • "lastDataOccurrence": "2020-06-10T00:00:00.000Z",
  • "data": {
    }
}

Conversations Tags Used

This metric shows the amount of used tags.

A tag can be linked to a conversation/to conversations to help defining the conversation. Tags can also be used to filter messages and conversations.

You can use the addMessage function to process tags.

Data is grouped by different periods depending on the given dates:

Period Group by
Greater than 5 years YEAR
Greater than 2 years QUARTER
Greater than 1 year MONTH
Greater than 31 days WEEK
Greater than 2 days DAY
Greater than 2 hours HOUR
Authorizations:
OAuth (api_credentials)
query Parameters
between
string <DateTime ISO8601>
Default: "30 days ago"

Optional
Data is fetched between two dates. This is the from or start date. Format is ISO8601.

and
string <DateTime ISO8601>
Default: "30 days after BETWEEN parameter"

Optional
Data is fetched between two dates. This is the to or end date. Format is ISO8601.

agent
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple agent(s). Make sure to urlencode the value.

channel
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more channels (ie. 'WHATSAPP', 'FACEBOOK_MESSENGER').

provider
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more providers (ie. TWILIO, SMOOCH).

identifier
Array of strings
Default: "*"

Optional
Get the statistics for one or more identities (ie. phone numbers, facebook messenger ids). Make sure to urlencode the value.

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getConversationsTagsUsed();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
{
  • "aggregatedBy": "DAY",
  • "firstDataOccurrence": "2020-06-01T00:00:00.000Z",
  • "lastDataOccurrence": "2020-06-10T00:00:00.000Z",
  • "data": {
    }
}

Conversation Resolve Times (Median)

Getting the median of the conversation resolve times.

A conversation is marked as resolved when there was no contact between you and the customer over this specific channel and identity for 24 hours. The last moment of contact will be marked as the time of resolvement.

Data is grouped by different periods depending on the dates given:

Period Group by
Greater than 5 years YEAR
Greater than 2 years and less than 5 years QUARTER
Greater than 1 year and less than 2 years MONTH
Greater than 31 days and less than 1 year WEEK
Greater than 2 day and less than 31 days DAY
Less than 1 day HOUR
Authorizations:
OAuth (api_credentials)
query Parameters
between
string <DateTime ISO8601>
Default: "30 days ago"

Optional
Data is fetched between two dates. This is the from or start date. Format is ISO8601.

and
string <DateTime ISO8601>
Default: "30 days after BETWEEN parameter"

Optional
Data is fetched between two dates. This is the to or end date. Format is ISO8601.

agent
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple agent(s). Make sure to urlencode the value.

channel
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more channels (ie. 'WHATSAPP', 'FACEBOOK_MESSENGER').

tag
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple tag(s). Make sure to urlencode the value.

provider
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more providers (ie. TWILIO, SMOOCH).

identifier
Array of strings
Default: "*"

Optional
Get the statistics for one or more identities (ie. phone numbers, facebook messenger ids). Make sure to urlencode the value.

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getConversationsResolveTimesMedian();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
{
  • "aggregatedBy": "DAY",
  • "firstDataOccurrence": "2020-06-01T00:00:00.000Z",
  • "lastDataOccurrence": "2020-08-13T00:00:00.000Z",
  • "data": {
    },
  • "aggregatedValue": 7930,
  • "previousAggregatedValue": 6789
}

Conversation Resolve Times (Average)

Getting the average of the conversation resolve times.

A conversation is marked as resolved when there was no contact between you and the customer over this specific channel and identity for 24 hours. The last moment of contact will be marked as the time of resolvement.

Data is grouped by different periods depending on the dates given:

Period Group by
Greater than 5 years YEAR
Greater than 2 years and less than 5 years QUARTER
Greater than 1 year and less than 2 years MONTH
Greater than 31 days and less than 1 year WEEK
Greater than 2 day and less than 31 days DAY
Less than 1 day HOUR
Authorizations:
OAuth (api_credentials)
query Parameters
between
string <DateTime ISO8601>
Default: "30 days ago"

Optional
Data is fetched between two dates. This is the from or start date. Format is ISO8601.

and
string <DateTime ISO8601>
Default: "30 days after BETWEEN parameter"

Optional
Data is fetched between two dates. This is the to or end date. Format is ISO8601.

agent
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple agent(s). Make sure to urlencode the value.

channel
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more channels (ie. 'WHATSAPP', 'FACEBOOK_MESSENGER').

tag
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple tag(s). Make sure to urlencode the value.

provider
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more providers (ie. TWILIO, SMOOCH).

identifier
Array of strings
Default: "*"

Optional
Get the statistics for one or more identities (ie. phone numbers, facebook messenger ids). Make sure to urlencode the value.

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getConversationsResolveTimesAverage();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
{
  • "aggregatedBy": "DAY",
  • "firstDataOccurrence": "2020-06-01T00:00:00.000Z",
  • "lastDataOccurrence": "2020-08-13T00:00:00.000Z",
  • "data": {
    },
  • "aggregatedValue": 7930,
  • "previousAggregatedValue": 6789
}

Average Messages per Conversation

Getting the average of the amount of the message in a conversation

To get the incoming or outgoing average messages per conversation you need to add the direction parameter with the corresponding value, "OUT" or "IN".

Data is grouped by different periods depending on the dates given:

Period Grouped by
Greater than 5 years YEAR
Greater than 2 years and less than 5 years QUARTER
Greater than 1 year and less than 2 years MONTH
Greater than 31 days and less than 1 year WEEK
Greater than 2 day and less than 31 days DAY
Less than 1 day HOUR
Authorizations:
OAuth (api_credentials)
query Parameters
between
string <DateTime ISO8601>
Default: "30 days ago"

Optional
Data is fetched between two dates. This is the from or start date. Format is ISO8601.

and
string <DateTime ISO8601>
Default: "30 days after BETWEEN parameter"

Optional
Data is fetched between two dates. This is the to or end date. Format is ISO8601.

agent
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple agent(s). Make sure to urlencode the value.

channel
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more channels (ie. 'WHATSAPP', 'FACEBOOK_MESSENGER').

tag
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple tag(s). Make sure to urlencode the value.

provider
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more providers (ie. TWILIO, SMOOCH).

identifier
Array of strings
Default: "*"

Optional
Get the statistics for one or more identities (ie. phone numbers, facebook messenger ids). Make sure to urlencode the value.

direction
string
Default: "ALL"
Enum: "IN" "OUT" "ALL"

Optional
Get the data for only received (IN) or send (OUT) messages. Or receive send and received (ALL).

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getConversationsMessagesAverage();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
{
  • "aggregatedBy": "HOUR",
  • "firstDataOccurrence": "2020-06-01T00:00:00.000Z",
  • "lastDataOccurrence": "2020-06-01T13:00:00.000Z",
  • "data": {
    },
  • "aggregatedValue": 1200,
  • "previousAggregatedValue": 1600
}

Unique Conversations

Getting unique conversations that are user or business-initiated.

Whenever your business replies to a user within the 24 hour customer care window, that message will be associated with a user-initiated conversation. Whenever your business initiates a conversation by sending a user a message outside the 24 hour customer care window, that message will be associated with a business-initiated conversation.

The shown amount is indicative.

Data is grouped by different periods depending on the dates given:

Period Group by
Greater than 5 years YEAR
Greater than 2 years and less than 5 years QUARTER
Greater than 1 year and less than 2 years MONTH
Greater than 31 days and less than 1 year WEEK
Greater than 2 day and less than 31 days DAY
Less than 1 day HOUR
Authorizations:
OAuth (api_credentials)
query Parameters
between
string <DateTime ISO8601>
Default: "30 days ago"

Optional
Data is fetched between two dates. This is the from or start date. Format is ISO8601.

and
string <DateTime ISO8601>
Default: "30 days after BETWEEN parameter"

Optional
Data is fetched between two dates. This is the to or end date. Format is ISO8601.

agent
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple agent(s). Make sure to urlencode the value.

channel
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more channels (ie. 'WHATSAPP', 'FACEBOOK_MESSENGER').

tag
Array of strings
Default: "*"

Optional
Get the statistics for one or mulitple tag(s). Make sure to urlencode the value.

provider
Array of strings[A-Z_]{2,100}
Default: "*"

Optional
Get the statistics for one or more providers (ie. TWILIO, SMOOCH).

identifier
Array of strings
Default: "*"

Optional
Get the statistics for one or more identities (ie. phone numbers, facebook messenger ids). Make sure to urlencode the value.

initiatedBy
string
Default: "ALL"
Enum: "USER" "BUSINESS" "ALL"

Optional
Get unique conversations that are user or business-initiated

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getConversationsUnique();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
{
  • "aggregatedBy": "DAY",
  • "firstDataOccurrence": "2020-06-01T00:00:00.000Z",
  • "lastDataOccurrence": "2020-06-10T00:00:00.000Z",
  • "data": {
    },
  • "aggregatedValue": 1981,
  • "previousAggregatedValue": 1468
}

Events

Resolve a conversation

Resolve a conversation.

When a conversation is resolved it will calculate metrics, like the resolve time. After resolving a conversation cannot receive more messages.

Authorizations:
OAuth (api_credentials)
Request Body schema: application/json
conversation
required
string (Conversation) <= 100 characters

A unique identifier which refers to a conversation. Could be an auto incremented identifier, GUID or any other unique alphanumeric reference.

provider
required
string (Messaging Provider) [A-Z_]{2,100}

The provider providing the messaging channel. Could be Facebook, Twilio, CM, Sunshine, SaySimple or any other. You are free to use any identifier as long as it only uses uppercase letters (A-Z) with a minimum length of 2 and a maximum length of 30. Please take care of setting the right key for your channel name, since this is not changeable afterwards.

channel
required
string (Channel) [A-Z_]{2,30}

The channel where the message is send over. You are free to use any identifier as long as it only uses uppercase letters (A-Z) with a minimum length of 2 and a maximum length of 30. Please take care of setting the right key for your channel name, since this is not changeable afterwards.

tenantChannelIdentifier
required
string (Identifier) <= 100 characters

A unique identifier to reach the tenant or the customer over a channel. Could be a phone number for SMS or WhatsApp, or the Facebook Messenger ID for Facebook Messenger.

agent
string (Customer Care Agent) <= 100 characters

The identifier of the customer care agent who handles this messages. Based on the direction property this could be the sender or the recipient. This identifier is a string and is the identifier of the agent, an email address for example.

tags
object (Tag Name)

A tag identifies one or multiple topic(s) for a conversation.

We define three types of tags. User tags, team tags and system tags. User tags are free form and can categorize the message. For example a message send by somebody famous with a question about their invoice could be tagged with 'VIP' and 'Finance'. To add these as tags you need to prefix them with user:. In this case we'd add user:VIP and user:Finance.

Team tags are used for linking a team to a message. You can only link one team per message. Multiple teams wont work, as it will only select the first added team. To add a team as a tag you need to prefix them with team:. In this particular case we'd add team:Sales.

System tags are reserved for certain metadata to create valuable metrics of these messages. Right now we have the following system tags defined:

Tag Description
system:paid_template A paid (WhatsApp) template is sent. This will occur if the customer care agent sends a message outside the customer care window (24h) Facebook defined
system:free_template The message sent was a template, but it was sent without any additional costs
time
required
string[0-2]?[0-9]:[0-9]?[0-9]

A time string (HH:MM) in UTC.

Responses

Request samples

Content type
application/json
{
  • "conversation": "1",
  • "provider": "SAYSIMPLE",
  • "channel": "SMS",
  • "tenantChannelIdentifier": "+31612345678",
  • "agent": "teddy_himself@teddies.com",
  • "tags": [
    ],
  • "time": "2020-02-14T12:03:59Z"
}

Response samples

Content type
application/json
""

Authenticate

You need to call this endpoint in order to swap your api key for a short-lived access token to use in subsequent requests.

Before your first request You need to have a registred public - private key pair.

  1. Generate a public - private key pair
    $ openssl genrsa -out private.pem 2048
    $ openssl rsa -in private.pem -pubout > public.pem
  2. Upload the public.pem to SaySimple via the dashboard.

These steps are only needed before the first time you wish to use the API. It is good practice though to refresh these keys from time to time.

Generate an authentication token Please generate a RS256 JSON Web Token with at least the following properties:

  • key: The API token you got from SaySimple.
  • iat: Issued at (seconds since Unix Epoch)
  • exp: Expires at (seconds since Unix Epoch). This needs to be a timestamp in the future, but a maximum of five minutes (300 seconds).

Sign this payload with the private key you generated.

Set this JWT as the Authorization header prefixed with 'Bearer' on your POST request.

You'll receive an JSON response with three properties: tokenType, accessToken and expiresIn.

{
    "tokenType": "Bearer",
    "accessToken": "eyJhbGci...eyJpc3MiZXN0Lm...adew39Sijas",
    "expiresIn": "2020-09-08T22:52:41.455Z"
}

This response is pretty self-explanatory. TokenType is always 'Bearer'. The access token is SaySimple generated JWT which can be used for 5 minutes to do subsequent requests. The time when it will expire is stated in the expiresIn as an ISO8601 formatted string.

You need to request a new access token if you hit the expire time.

Be aware of the change of the endpoint URL (domain) for auth resources.

Responses

Request samples

// The SDK will handle the authentication requests for you
// It will also generate a new access token if you hit the
// expiration time.

// !! BE AWARE !!
// -------------------
// If you use this SDK as a frontend package don't
// expose your secret in your code. This will give
// people the opportunity to use the API on your behalf.
// -------------------
// !! BE AWARE !!

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

Response samples

Content type
application/json
{
  • "tokenType": "Bearer",
  • "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhcGktZG9jdW1lbnRhdGlvbi5zYXlzaW1wbGUuaW8iLCJjaWQiOjEsInN1YiI6MjU1MTYsImFwaVRva2VuIjp0cnVlLCJpYXQiOjE2MDA2Nzg4MDQsImV4cCI6MTYwMDY3OTEwNH0.TunLYFwoV9rxzFYoYBPLZZ9LhvqKHsWOExMYtD7JaiUpoEdSaljWkCdeh0yDHQuFlEx4hws6q2oXWekdpyANd0NM6hs7VsRzWb5h2KmPWdDHueAETZHzx9rVgH94GVdYNDRPN9bSezSfBf7e7TlY1L_sxD_-kn-T9BUUK3BPjzquH0AgKzbYzJeKHQivkaLEJaDaojtwV8ZrGIlUuxrfr81ELpe0CXbG621skRNHQdPnf3Zta8WHNmqoQY9r4s8JeucIphjuuZPVjBnyA6dzgsBa2Zyx4tNbBrmd3rsW4sd8mDVB7H6clvWwCFbVvC-rikD_9UdI9-LMvKuAMnAhNzyeleHfLYwd8RmpFSJ7ssQCHYJEBoLcrQUuzgUQyL7p_LcJMcwjvvy96SsjJPYDXkbHNjh7cLtQSz4vlZqQj4XwyFg2vbXdDz4Lz9aWOE6fWCgOLktd7wFxOBiEO8CIonAEQVbCmNZBAXhNsWTVV6mZKLWp8d0VxYxSadX2B_2AXTqnas33sTIXTs3w_Crxe3zl4RlPoykdudtU4H1AzFjZlwBgZE8GVK7JflNOwJBxu595Z-3cgiQnl9_hgpjzl0Jj2VUOyFYyNFmufAlMMEpcZnjqtkm958czl8Z9-76-gwRtgntMTFS3sadaBcTfQIhu43m3UkSBjJ9mmz215ZY",
  • "expiresIn": "2020-09-21T09:05:04.916Z"
}

Tags

List all tags

Getting a list of all tags that were linked to a conversation.

Authorizations:
OAuth (api_credentials)

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getTags();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
[
  • "agent_for@teddies.co.uk",
  • "manager@teddies.co.uk"
]

Teams

List all teams

Getting a list of objects containing teams whom have been used on the platform now and in the past.

Authorizations:
OAuth (api_credentials)

Responses

Request samples

const SaySimple = require("@saysimple/node-sdk");
const IntelligenceClient = SaySimple.Intelligence.V1({
  '[API TOKEN]',
  '[SECRET]'
});

(async () => {
  const result = await IntelligenceClient.getTeams();

  process.stdout.write(JSON.stringify(result), null, "\t");
})();

Response samples

Content type
application/json
[
  • "Finance",
  • "Support"
]