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
Array of strings (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 preix 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.

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"
}

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').