Context API

The Seamly Context API provides a public api to interact with the context of running conversations.

Fetching data happens based on an  external_lookup_id . This id must be set within the conversation and can then be used to get context data while the conversation is running.

Requirements

To use the Context API you will need the following:

• A Seamly api key for either the User Acceptance Testing (UAT) or the production environment
• An activated configuration of the Context API

There are some other things to take into account:

• The request will only allow access to specifically configured fields. This must be configured on the Seamly side.
• The request can only succeed if the conversation with the specific  external_lookup_id  is still running. A conversation typically runs some time after the user hung up / left the conversation, however this is not indefinitely. Typically this is 1 minute, but depends on the specific account configuration.

Please get in touch with  support@seamly.ai  if you need help with these requirements.

UAT and production environment

We provide two environments for you to connect to; a User Acceptance Testing (UAT) and a production environment. The base URLs of these environments are:

• UAT: https://api.uat.seamly-app.com/context/v1
• Production: https://api.seamly-app.com/context/v1

OpenAPI specification

The Context Api provides a REST Api to interact with the context of running conversations.

Please have a look at the  OpenApi specification  of the REST Api.

Security

The Context API supports two ways to ensure access to the api is limited. You can use one or both of them. The API does not work without this.

The options are:

1. A  HMAC signature  that includes the current time and a shared secret,
2. An allowlist of IP addresses that are allowed to access the API.

HMAC signature

When making use of the HMAC signature all requests should have a  X-Seamly-Signature  header containing a unix epoch timestamp in seconds (as  t  parameter) and a scheme parameter ( v1 ) containing the signature. The signature is calculated with a secret and the timestamp. The secret will be provided to you.

The header looks like this:

X-Seamly-Signature: t=1597999043,v1=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

The signature is generated using a hash-based message authentication code ( HMAC ) with  SHA-256 .

Signature creation

Creation should be done as follows:

1. Create timestamp

   The header contains a timestamp to make sure we do not send in a plaintext version of the shared secret. Use the current unix epoch timestamp in seconds.

2. Create a payload string

   For GET-requests:

   • The unix timestamp as string

   For example:  1597999043

   Concatenate the following for POST-requests:

   • The unix timestamp as string
   • A dot ( . )
   • The request body as string

   For example:  1597999043.{payload:{}}

3. Generate the signature

   Generate the HMAC with SHA-256 hash function with the previously generated payload string and the configured secret. The output should be a hex string.

   Example in NodeJS:

   import { createHmac } from 'crypto'
   
   const hmac = createHmac('SHA256', secret)
   hmac.update(payload_from_previous_step)
   
   const result = hmac.digest()
   const signature = result.toString('hex')

   Example in Ruby:

   require 'openssl'
   signature = OpenSSL::HMAC.hexdigest("SHA256", secret, payload_from_previous_step)

4. Combine timestamp and signature in header

   After generating the signature, prefix it with  v1= ; combine that with the timestamp prefixed with  t=  and put those in the header together separated by a comma.