Mesaic API API Reference

Welcome to the Mesaic API documentation. This API is intended to help connect external services to the Mesaic platform. All operations, objects and authorization details to interact with the API are described in this document. All essential functions have an example in the right column of the screen. If you do find anything you don't understand or would love to have more input on, please don't hesitate to send us an email.

API Endpoint

https://api.mesaic.io/v1
Contact: support@mesaic.co
Request Content-Types: application/json
Response Content-Types: application/json
Schemes: https
Version: v1

Authorization

The Mesaic API is a HTTP-based REST endpoint using OAuth2 for authorization. After acquiring an access token you are ready to submit requests to the API, depending on the validity of your token's read and write access rights within the Mesaic Platform. Access rights are listed for every operation in terms of scopes.

Versioning

The Mesaic platform is in constant development. This includes changes to how the APIs works. As such, we will introduce new features that enhance the interfaces to our platform. We will introduce a new API versions whenever any changes cause incompatibilities with the current version. We always keep our customers and partners will be informed about releases of new version releases, and the live-time and deprecation of older ones.

Versions are encoded in the path of any request (e.g. /v1/users).

Request and response formats

This API accepts and provides JSON-encoded data on all endpoints. When sending a payload body, you must set the Content-Type HTTP header to application/json. The response will contain the same header.

Some endpoints include path parameters or url-encoded query parameters. These are described accordingly in this documentation.

Errors

Standard HTTP status codes apply.

Requesting a resource without permissions will usually not result in an error response, but rather return null or an empty collection. If errors occur, they are likely to be usage errors or internal server errors. If these errors persists, please contact Mesaic for support.

Example:

Request (via cURL)

curl http://localhost:3006/v1/users \
  -X POST \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "chatIntro": "Hi",
    "email": "test+customer5@mesaic.co",
    "firstName": "Customer",
    "lastName": "Five",
    "localeId": "de",
    "phoneNumber": "+491761234567",
    "tenantId": "07a4be0d-376e-4603-b8dc-dd1db58ba5b5",
    "variantId": "a0950436-c4f7-4870-9003-454fcd9a0e47"
  }'

Response

{
  "id": "e3951d33-bdbe-4008-aec8-3abc9f9063b8",
  "firstName": "Customer",
  "lastName": "Five",
  "email": "test+customer5@mesaic.co",
  "phoneNumber": "+491761234567",
  "tenantId": "07a4be0d-376e-4603-b8dc-dd1db58ba5b5"
}

Authentication

OAuth2

For most API requests, authorization with a valid token is required. This API performs authorization using OAuth2. For authorization of a request, a valid token must be acquired.

The authorization API supports the following OAuth2 grant types:

  • Authorization Code
  • Client Credentials
  • Implicit
  • Refresh Token
  • Password (not allowed for third party clients)

The use case of your application will determine which grant type you will use.

Please note that the API endpoint for the authorization API differs from the public API.

For details on the OAuth2 standard, visit oauth.net.

type
oauth2
flow
application
tokenUrl
https://api.mesaic.io/v1/auth
scopes
all

The main scope with access to everything

read:users

Permission to read user information

write:users

Permission to modify user information

Retrieve a token with valid login credentials like this:

curl https://api.mesaic.io/v1/auth \
  -H 'Content-Type: application/json' \
  -d '{
  "grant_type": "password",
  "username": "test+user@example.com",
  "password": "mesaic",
  "client_id": "c0ac5614-89b5-4e0c-a646-167bc0676b0f"
}'

A successful response is a JSON formatted object like this:

{
  "access_token": "9ed12d28de6334bc0d...d3",
  "refresh_token": "20ed19c1668d8c3da1...3f",
  "scope": ["*"],
  "expires_in": 604799,
  "token_type": "Bearer"
}

This access token needs to be sent in the Authorization header for all HTTP requests:

curl -H 'Authorization: Bearer 9ed12d28de6334bc0d...d3'  https://api.mesaic.io/v1/users

Files

Create a file

POST /files

Creates a new file

fileData: string

The file data as base64

fileName: string

The name of the file

format: string

The file format

Request Example
{
  "fileData": "SOME DATA",
  "fileName": "example.pdf",
  "format": "application/pdf"
}
201 Created

Creating the file was successful

Response Content-Types: application/json
Response Example (201 Created)
{
  "id": "dea1737b-afdb-4b38-9ba8-791119054484",
  "src": "https://s3-eu-west-1.amazonaws.com/test/order/dea1737b-afdb-4b38-9ba8-791119054484"
}

Get file by id

GET /files/{id}

Gets the file by its id

id: string
in path

The unique id of the image to get

200 OK

The file was found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "dea1737b-afdb-4b38-9ba8-791119054484",
  "src": "https://s3-eu-west-1.amazonaws.com/test/order/dea1737b-afdb-4b38-9ba8-791119054484"
}

Images

Get image by id

GET /images/{id}

Gets the image by its id

id: string
in path

The unique id of the image to get

200 OK

The image was found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "f8906636-b31b-4ee8-b259-0ca87cd748e2",
  "src": "https://s3-eu-west-1.amazonaws.com/int.mesaic.io/images/d80fddca-80fe-4f3a-be8a-0c90bcef0f87",
  "width": 600,
  "height": 400,
  "format": "png"
}

Upload image

POST /images

Uploads images and creates database entry for it

imageData: string

The image data as base64

Request Example
{
  "imageData": "imageData: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYAB..."
}
201 Created

Created image successfully

Response Content-Types: application/json
Response Example (201 Created)
{
  "id": "f8906636-b31b-4ee8-b259-0ca87cd748e2",
  "src": "https://s3-eu-west-1.amazonaws.com/int.mesaic.io/images/d80fddca-80fe-4f3a-be8a-0c90bcef0f87",
  "width": 600,
  "height": 400,
  "format": "png"
}

Threads

List all threads

GET /threads

Lists all threads for the authenticated tenant

200 OK

Fetching the threads was successful

type
Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "id": "a0950436-c4f7-4870-9003-454fcd9a0e47",
    "userId": "a0950436-c4f7-4870-9003-454fcd9a0e47",
    "variantId": "3e75864f-3bf2-4df7-b262-a25a09771baf",
    "createdAt": "2018-11-20T13:45:13.000Z",
    "updatedAt": "2018-11-20T13:45:13.000Z",
    "currentConversationContext": {
      "id": "a0950436-c4f7-4870-9003-454fcd9a0e47",
      "orderId": "a0950436-c4f7-4870-9003-454fcd9a0e47",
      "userIds": [
        "2ea89f5b-6cae-455a-8f9f-616cccff14af"
      ]
    }
  }
]

Create a thread

POST /threads

Creates a new thread

variantId: string

The id of the variant for which the thread shall be created

entrypointName: string

The entrypoint for which the thread shall be created

Request Example
{
  "variantId": "a0950436-c4f7-4870-9003-454fcd9a0e47",
  "entrypointName": "checkout"
}
201 Created

The thread was created successfully

Response Content-Types: application/json
Response Example (201 Created)
{
  "id": "a0950436-c4f7-4870-9003-454fcd9a0e47",
  "userId": "a0950436-c4f7-4870-9003-454fcd9a0e47",
  "variantId": "3e75864f-3bf2-4df7-b262-a25a09771baf",
  "createdAt": "2018-11-20T13:45:13.000Z",
  "updatedAt": "2018-11-20T13:45:13.000Z",
  "currentConversationContext": {
    "id": "a0950436-c4f7-4870-9003-454fcd9a0e47",
    "orderId": "a0950436-c4f7-4870-9003-454fcd9a0e47",
    "userIds": [
      "2ea89f5b-6cae-455a-8f9f-616cccff14af"
    ]
  }
}

Get thread by id

GET /threads/{id}

Gets the thread by its id

id: string
in path

The unique id of the thread to get

200 OK

The thread was found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "a0950436-c4f7-4870-9003-454fcd9a0e47",
  "userId": "a0950436-c4f7-4870-9003-454fcd9a0e47",
  "variantId": "3e75864f-3bf2-4df7-b262-a25a09771baf",
  "createdAt": "2018-11-20T13:45:13.000Z",
  "updatedAt": "2018-11-20T13:45:13.000Z",
  "currentConversationContext": {
    "id": "a0950436-c4f7-4870-9003-454fcd9a0e47",
    "orderId": "a0950436-c4f7-4870-9003-454fcd9a0e47",
    "userIds": [
      "2ea89f5b-6cae-455a-8f9f-616cccff14af"
    ]
  }
}

List orders of a thread

GET /threads/{id}/orders

Lists all orders that are associated with the thread

id: string
in path

The unique id of the thread with which to search for orders

200 OK

The thread and associated orders were found

type
Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "id": "a0950436-c4f7-4870-9003-454fcd9a0e47",
    "orderNo": 180011,
    "createdAt": "2018-11-20T13:45:13.000Z",
    "lineItems": [
      {
        "id": "a0950436-c4f7-4870-9003-454fcd9a0e47"
      }
    ],
    "images": [
      {
        "id": "f8906636-b31b-4ee8-b259-0ca87cd748e2",
        "src": "https://s3-eu-west-1.amazonaws.com/int.mesaic.io/images/d80fddca-80fe-4f3a-be8a-0c90bcef0f87",
        "width": 600,
        "height": 400,
        "format": "png"
      }
    ],
    "defaultAddress": {
      "latitude": 53.5521729,
      "longitude": 9.9853509,
      "formatted": "Axel-Springer-Platz 3 - 20355 Hamburg"
    },
    "billingAddress": "object",
    "orderAddresses": "array",
    "coupon": "object",
    "startDate": "string",
    "status": "string",
    "userId": "a0950436-c4f7-4870-9003-454fcd9a0e47"
  }
]

List all events of a thread

GET /threads/{id}/events

Lists all events that are associated with the thread

id: string
in path

The unique id of the thread with which to search for events

200 OK

The thread and associated events were found

type
Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "id": "6454d801-ab7e-4ecc-bf4c-814d5a09387e",
    "typeName": "core/chat-message",
    "authorId": "6454d801-ab7e-4ecc-bf4c-814d5a09387e",
    "processingStatus": "processed",
    "hasReplies": false,
    "message": "Hello!",
    "createdAt": "2018-11-20T07:58:56.056Z"
  }
]

Create an event

POST /threads/{id}/events

Creates a new event and attaches it to a thread

conversationContextId: string

The conversation context id

typeName: string

The event type to be attached

data: object

The data to be used for event creation

id: string
in path

The unique id of the thread to which to attach the event

Request Example
{
  "conversationContextId": "dea1737b-afdb-4b38-9ba8-791119054484",
  "typeName": "core/chat-message",
  "data": {
    "storeMessageOrImage": {
      "message": "Hi!!!"
    }
  }
}
201 Created

The thread was found, the event created and attached to the thread

type
Response Content-Types: application/json
Response Example (201 Created)
[
  {
    "id": "6454d801-ab7e-4ecc-bf4c-814d5a09387e",
    "typeName": "core/chat-message",
    "authorId": "6454d801-ab7e-4ecc-bf4c-814d5a09387e",
    "processingStatus": "processed",
    "hasReplies": false,
    "message": "Hello!",
    "createdAt": "2018-11-20T07:58:56.056Z"
  }
]

List all messages of a thread

GET /threads/{id}/messages

Lists all messages that are associated with the thread

id: string
in path

The unique id of the thread with which to search for messages

200 OK

The thread and associated messages were found

type
Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "id": "6454d801-ab7e-4ecc-bf4c-814d5a09387e",
    "imageId": "6454d801-ab7e-4ecc-bf4c-814d5a09387e",
    "lineItemId": "6454d801-ab7e-4ecc-bf4c-814d5a09387e",
    "authorId": "6454d801-ab7e-4ecc-bf4c-814d5a09387e",
    "replyForEventId": "6454d801-ab7e-4ecc-bf4c-814d5a09387e",
    "message": "Hello!",
    "createdAt": "2018-11-20T07:58:56.056Z"
  }
]

User

Get user by id

GET /users/id

Gets the user by its id

id: string
in path

The unique id of the thread to get

200 OK

The user was found

Response Content-Types: application/json
Response Example (200 OK)
{
  "email": "max.mustermann@example.com",
  "firstName": "Max",
  "lastName": "Mustermann",
  "phoneNumber": 491571234567,
  "chatIntro": "Dear",
  "localeId": "en",
  "variant": "a0950436-c4f7-4870-9003-454fcd9a0e47"
}

List all users

GET /users

Lists all threads for the authenticated tenant

200 OK

Fetching the users was successful

type
Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "email": "max.mustermann@example.com",
    "firstName": "Max",
    "lastName": "Mustermann",
    "phoneNumber": 491571234567,
    "chatIntro": "Dear",
    "localeId": "en",
    "variant": "a0950436-c4f7-4870-9003-454fcd9a0e47"
  }
]

Create a user

POST /users

Creates a new user

tenantId: string

The id of the tenant for which the thread shall be created

variantId: string

The id of the variant for which the thread shall be created

email: string

The email of the user, used as the login identifier

firstName: string

The first name of the user

lastName: string

The last name of the user

phoneNumber: string

The phone number of the user

chatIntro: string

Automated chat messages begin with this string

localeId: string

The locale to which all frontends are translated for this user; currently supported values are [en, de]

onBehalf: boolean

When set to true, the user is created on behalf of another user

Request Example
{
  "tenantId": "07a4be0d-376e-4603-b8dc-dd1db58ba5b5",
  "variantId": "a0950436-c4f7-4870-9003-454fcd9a0e47",
  "email": "max.mustermann@example.com",
  "firstName": "Max",
  "lastName": "Mustermann",
  "phoneNumber": 491571234567,
  "chatIntro": "Dear",
  "localeId": "en",
  "onBehalf": false
}
201 Created

The user was created successfully

Response Content-Types: application/json
Response Example (201 Created)
{
  "email": "max.mustermann@example.com",
  "firstName": "Max",
  "lastName": "Mustermann",
  "phoneNumber": 491571234567,
  "chatIntro": "Dear",
  "localeId": "en",
  "variant": "a0950436-c4f7-4870-9003-454fcd9a0e47"
}

Edit user

PUT /users/{id}

Modifies an existing user

email: string

The email of the user, used as the login identifier

firstName: string

The first name of the user

lastName: string

The last name of the user

phoneNumber: string

The phone number of the user

chatIntro: string

Automated chat messages begin with this string

localeId: string

The locale to which all frontends are translated for this user; currently supported values are [en, de]

salesForceId: string

The salesforce id for this user

id: string
in path

Id of the user to be modified

Request Example
{
  "email": "max.mustermann@example.com",
  "firstName": "Max",
  "lastName": "Mustermann",
  "phoneNumber": 491571234567,
  "chatIntro": "Dear",
  "localeId": "en",
  "salesForceId": "0089o00002SXqL2BBL"
}
200 OK

The user was found and modified successfully

Response Content-Types: application/json
Response Example (200 OK)
{
  "email": "max.mustermann@example.com",
  "firstName": "Max",
  "lastName": "Mustermann",
  "phoneNumber": 491571234567,
  "chatIntro": "Dear",
  "localeId": "en",
  "variant": "a0950436-c4f7-4870-9003-454fcd9a0e47"
}

Workflows

Get workflow

GET /workflows/{revisionId}

Gets the workflow by its revision id

revisionId: number
in path

The id of the revision for the workflow to get

200 OK

The workflow was found

Response Content-Types: application/json

Schema Definitions

File: object

id: string

The id of saved file

src: string

Source of created file

Example
{
  "id": "dea1737b-afdb-4b38-9ba8-791119054484",
  "src": "https://s3-eu-west-1.amazonaws.com/test/order/dea1737b-afdb-4b38-9ba8-791119054484"
}

Image: object

id: string

Unique identifier

src: string

The URL from where the actual image file shall be retrieved

width: number

Width of the image in pixels

height: number

Height of the image in pixels

format: string

Filetype of the image

Example
{
  "id": "f8906636-b31b-4ee8-b259-0ca87cd748e2",
  "src": "https://s3-eu-west-1.amazonaws.com/int.mesaic.io/images/d80fddca-80fe-4f3a-be8a-0c90bcef0f87",
  "width": 600,
  "height": 400,
  "format": "png"
}

Event: object

id: string

The event id

typeName: string

The event type

authorId: string

The event author id

processingStatus: string

The status of the event

hasReplies: boolean

If the message has replies or not

message: string

The event message

createdAt: string

When the event was created

Example
{
  "id": "6454d801-ab7e-4ecc-bf4c-814d5a09387e",
  "typeName": "core/chat-message",
  "authorId": "6454d801-ab7e-4ecc-bf4c-814d5a09387e",
  "processingStatus": "processed",
  "hasReplies": false,
  "message": "Hello!",
  "createdAt": "2018-11-20T07:58:56.056Z"
}

Message: object

id: string

The message event id

imageId: string

The message image id

lineItemId: string

The message line item id

authorId: string

The message author id

replyForEventId: string

The message reply for event id

message: string

The message

createdAt: string

When the event was created

Example
{
  "id": "6454d801-ab7e-4ecc-bf4c-814d5a09387e",
  "imageId": "6454d801-ab7e-4ecc-bf4c-814d5a09387e",
  "lineItemId": "6454d801-ab7e-4ecc-bf4c-814d5a09387e",
  "authorId": "6454d801-ab7e-4ecc-bf4c-814d5a09387e",
  "replyForEventId": "6454d801-ab7e-4ecc-bf4c-814d5a09387e",
  "message": "Hello!",
  "createdAt": "2018-11-20T07:58:56.056Z"
}

LineItem: object

id: string

A unique identifier

Example
{
  "id": "a0950436-c4f7-4870-9003-454fcd9a0e47"
}

Order: object

id: string

A unique identifier

orderNo: string

The formatted order number, consisting of the year (2 digits), the day with leading zeros (3 digits) & a unique, increasing integer.

createdAt: string

When the order was created

lineItems: LineItem
LineItem
images: Image
Image
defaultAddress: object
latitude: number

latitude

longitude: number

longitude

formatted: string

formatted representation

billingAddress: object
orderAddresses: array
coupon: object
startDate: string
status: string
userId: string

unique identifier for the order user

Example
{
  "id": "a0950436-c4f7-4870-9003-454fcd9a0e47",
  "orderNo": 180011,
  "createdAt": "2018-11-20T13:45:13.000Z",
  "lineItems": [
    {
      "id": "a0950436-c4f7-4870-9003-454fcd9a0e47"
    }
  ],
  "images": [
    {
      "id": "f8906636-b31b-4ee8-b259-0ca87cd748e2",
      "src": "https://s3-eu-west-1.amazonaws.com/int.mesaic.io/images/d80fddca-80fe-4f3a-be8a-0c90bcef0f87",
      "width": 600,
      "height": 400,
      "format": "png"
    }
  ],
  "defaultAddress": {
    "latitude": 53.5521729,
    "longitude": 9.9853509,
    "formatted": "Axel-Springer-Platz 3 - 20355 Hamburg"
  },
  "billingAddress": "object",
  "orderAddresses": "array",
  "coupon": "object",
  "startDate": "string",
  "status": "string",
  "userId": "a0950436-c4f7-4870-9003-454fcd9a0e47"
}

Thread: object

id: string

A unique identifier

userId: string

The user identifier

variantId: string

The variant identifier

createdAt: string

When the thread was created

updatedAt: string

The last updated date for the thread

currentConversationContext: object
id: string

A unique identifier

orderId: string

The order identifier

userIds: array

The user ids list

Example
{
  "id": "a0950436-c4f7-4870-9003-454fcd9a0e47",
  "userId": "a0950436-c4f7-4870-9003-454fcd9a0e47",
  "variantId": "3e75864f-3bf2-4df7-b262-a25a09771baf",
  "createdAt": "2018-11-20T13:45:13.000Z",
  "updatedAt": "2018-11-20T13:45:13.000Z",
  "currentConversationContext": {
    "id": "a0950436-c4f7-4870-9003-454fcd9a0e47",
    "orderId": "a0950436-c4f7-4870-9003-454fcd9a0e47",
    "userIds": [
      "2ea89f5b-6cae-455a-8f9f-616cccff14af"
    ]
  }
}

User: object

email: string

The email of the user. This is used as the login identifier

firstName: string

The first name of the user

lastName: string

The last name of the user

phoneNumber: string

The phone number of the user

chatIntro: string

Automated chat messages begin with this string

localeId: string

The locale to which all frontends re translated for this user; currently supported values are [en, de]

variant: string

The variant with which the user was created

Example
{
  "email": "max.mustermann@example.com",
  "firstName": "Max",
  "lastName": "Mustermann",
  "phoneNumber": 491571234567,
  "chatIntro": "Dear",
  "localeId": "en",
  "variant": "a0950436-c4f7-4870-9003-454fcd9a0e47"
}