Context API

The Seamly Context API provides a public API to interact with the context of ongoing calls.

Fetching data happens based on an  external_lookup_id . This ID must be set within the call and can then be used to get context data while it is active.

Requirements

To use the Context API you will need the following:

• A Seamly API key for the 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 while context data for the specified external_lookup_id remains available. Context typically remains available for approximately one minute after the caller hangs up. The exact duration depends on the account configuration.

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

Environment

We provide a production environment. The base URL for the production environment is:

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

OpenAPI specification

The Context API provides a REST API to interact with the context of ongoing calls.

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 an  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 Node.js:

   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.