SaySimple public API (2021-05-05T12:13:46Z)

Download OpenAPI specification:Download

The SaySimple Public API - allow you to interact with the messaging part of SaySimple.

Global aggreements

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

    • 2020-01-15T15:00:39Z
  2. 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. 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/messaging/v1
basePath messaging/v1
documentationEndpoint https://docs.saysimple.io/messaging/index.html

Before you can use the SaySimple API, you need to authenticate, so SaySimple knows who you are and checks the correct permissions. Authentication is done by a private and public key pair in combination with an API key as JWT (JSON Web Tokens). The API key is provided by SaySimple. The private and public key pair needs to be generated by the API user.

Keys and Tokens

  • ❌ Do NOT share your API key, private key and JWT tokens with others.

There are 3 steps to take:

  1. Generate a private- and public key pair
  2. Generate JWT
  3. Authentication request

Private and public key pair

To generate a key pair, you can use the OpenSSL tool. This will create two files in the current directory, private.pem and public.pem:
Generate key pairs

// Generate private key. Additionally, you can also specify the validity of the certificate
openssl genrsa -out private.pem 2048
// Extract the public key from the private key
openssl rsa -in private.pem -pubout > public.pem

Please note
Saysimple needs your public key (public.pem file), so it can validate your signature.

JWT

After you have generated the key pair, you need to generate a JSON Web Token. A JWT is a string that consists of 3 parts: the header, the payload and the signature. To generate a JWT, there are libraries available in several programming languages. Please see the website jwt.io. In the example below, we use NodeJS.

Generate JWT with NodeJS

const jwt        = require("jsonwebtoken");
const fs         = require("fs");
const privateKey = fs.readFileSync("private.pem");  // The path to the generated private.pem file.

const jwtToken = jwt.sign({
key: "<Your SaySimple API key>", // SaySimple will provide you the API key.
apiToken: true,
}, privateKey, {
algorithm: "RS256",
expiresIn: 300, // Number of seconds the token will expire. Max value allowed: 300 (5 minutes)
notBefore: 0, // The generated token is not valid before given NumericDate (timestamp). Use 0 to be valid directly from moment the token is generated.
});
  • The generated token will expire in the value given in "expiresIn". The max value is 300s (5 minutes). This means that you need to regenerate the token within every expiresIn period.

Generate JWT with PHP

<?php
// CLI command to install JWT library: composer require "firebase/php-jwt"
require __DIR__ . '/../vendor/autoload.php'; // Path to the Composer autoload class.
use \Firebase\JWT\JWT;

$privateKey = file_get_contents("private.pem"); // The path to the generated private.pem file to get the contents of it.

$payload = [
    "key"      => "<Your SaySimple API key>", // SaySimple will provide you the API key.
    "apiToken" => true,
    "iat"      => 1618908113,
    "exp"      => 1618908413, // Timestamp that the token will expire. Max value allowed: current timestamp + 300 seconds (5 minutes).
    "nbf"      => 0 // // The generated token is not valid before given timestamp. Use 0 to be valid directly from moment the token is generated.
];

$jwtToken = JWT::encode($payload, $privateKey, "RS256");
echo $jwtToken . "\n";
  • The generated token will expire in the value given in "exp". The max value is the current timestamp plus 300 seconds (5 minutes). This means that you need to regenerate the token within every exp period.

Regenerate JWT
Before the generated JWT will expire (given as expiresIn attribute), you need to regenerate the JWT.

Authentication request

Please make sure:

  1. You have the API key provided by SaySimple.
  2. SaySimple has your public key file.
  3. You have successfully generated the JWT.

Request

POST https://api.saysimple.io/messaging/v1/auth/authenticate
  • You need to pass the generated JWT as Authorization Bearer header

Response
If the authenticate request has been completed successfully, an access token is returned, together with the token type and expiry date. The access token is valid for a period of 5 minutes. If the token has been expired, you need to re-authenticate to get a new authorization token. Example authentication response

{
      "tokenType": "Bearer",
      "accessToken: "eyJhbGci...eyJpc3MiZXN0Lm...adew39Sij...",
      "expiresIn": "2020-09-08T22:52:41.455Z"
  }
  • The returned access token can be used to do sub-sequent requests

Authentication

Authorizer

Security Scheme Type API Key
Header parameter name: Authorization

Templates

Retrieve all templates

Retrieve all templates

Authorizations:
header Parameters
Authorization
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Messages

Retrieve a message

Retrieve a message

Authorizations:
path Parameters
id
required
string

Message id

header Parameters
Authorization
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "customerId": 0,
  • "userId": 0,
  • "channelId": 0,
  • "time": "2019-08-24T14:15:22Z",
  • "identityId": 0,
  • "conversationId": 0,
  • "direction": "string",
  • "status": "string",
  • "system": 0,
  • "message": "string",
  • "externalReference": "string",
  • "createdAt": "2019-08-24T14:15:22Z"
}

Send a message

Send a message

Authorizations:
header Parameters
Authorization
required
string

JWT Token

Request Body schema: application/json

Message Template

tokenType
string
accessToken
string
expiresIn
string <date>
required
object
required
object
object
required
object

Responses

Request samples

Content type
application/json
{
  • "tokenType": "string",
  • "accessToken": "string",
  • "expiresIn": "2019-08-24",
  • "from": {
    },
  • "to": {
    },
  • "metadata": {
    },
  • "content": {
    }
}

Response samples

Content type
application/json
0

Authenticate

Authenticate with JWT

Authenticate with JWT

header Parameters
Authorization
required
string

JWT Token

Responses

Response samples

Content type
application/json
{
  • "tokenType": "string",
  • "accessToken": "string",
  • "expiresIn": "2019-08-24"
}

Contacts

Retrieve contact by id

Retrieve contact by id

Authorizations:
path Parameters
id
required
string

Contact id

header Parameters
Authorization
required
string

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "customerId": 0,
  • "originalId": 0,
  • "name": "string",
  • "photo": "string",
  • "countryId": 0,
  • "email": "string",
  • "phone": "string",
  • "street": "string",
  • "houseNumber": "string",
  • "zipCode": "string",
  • "city": "string",
  • "province": "string",
  • "country": "string",
  • "reference": "string",
  • "company": "string",
  • "jobTitle": "string",
  • "defaultChannelId": 0,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Patch contact by id

Patch contact by id

Authorizations:
path Parameters
id
required
string

Contact id

header Parameters
Authorization
required
string

Responses

Response samples

Content type
application/json
{ }

Retrieve all contacts

Retrieve all contacts

Authorizations: