Session API

The Session API allows you to create authentication sessions that can be used for subsequent API calls. This is the first step in the integration process.

Create Session

POST /api/widget/session

Creates a new session and returns a token that can be used for authentication in other API calls.

Request Parameters

Parameter	Type	Required	Description
`email`	string	Optional	Email address of the user. If not provided, an anonymous session will be created.
`emailHash`	string	Conditional	HMAC hash of the email and timestamp. Required if email is provided.
`mailboxSlug`	string	Yes	Slug of the mailbox to connect to.
`timestamp`	number	Conditional	Current timestamp in milliseconds. Required if email is provided.
`customerMetadata`	object	No	Additional metadata about the customer.
`customerMetadata.value`	number	No	Numeric value representing the customer's worth/revenue.
`customerMetadata.name`	string	No	Name of the customer.
`customerMetadata.links`	object	No	Key-value pairs of links related to the customer.
`currentURL`	string	Yes	The current URL where the chat is being initiated.

Example Request Body

{
  "email": "customer@example.com",
  "emailHash": "a1b2c3d4e5f6...",
  "mailboxSlug": "your-mailbox",
  "timestamp": 1693324800000,
  "customerMetadata": {
    "value": 500,
    "name": "John Doe",
    "links": {
      "Profile": "https://example.com/users/john",
      "Orders": "https://example.com/users/john/orders"
    }
  },
  "currentURL": "https://example.com/products"
}

Response

Field	Type	Description
`valid`	boolean	Whether the authentication was successful.
`token`	string	JWT token to use for subsequent API calls.
`showWidget`	boolean	Whether the chat widget should be shown to this customer based on your settings.
`notifications`	array	Optional array of unread notifications for the customer.

Example Response

{
  "valid": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "showWidget": true,
  "notifications": []
}

Error Responses

Status Code	Error	Description
400	`Invalid request parameters`	The request is missing required parameters or they are invalid.
400	`Invalid mailbox`	The specified mailbox does not exist.
401	`Email authentication fields missing`	Email provided but timestamp or emailHash is missing.
401	`Timestamp is too far in the past`	The timestamp is outside the acceptable range (1 hour).
401	`Invalid HMAC signature`	The provided emailHash does not match the computed hash.

Authentication

Generating the HMAC Hash

To authenticate a user with their email, you need to generate an HMAC hash using:

The user's email
A timestamp
Your mailbox's HMAC secret

Prepare Your Data

Gather the required information:

User's email address
Current timestamp in milliseconds
Your mailbox's HMAC secret from the Helper dashboard

Create the Message String

The format for the HMAC input is: email:timestamp

For example: customer@example.com:1693324800000

Generate the Hash

Use the HMAC-SHA256 algorithm to generate a hexadecimal hash of the message string.

Here's how to generate the hash in different languages:

Node.js

const crypto = require('crypto');
 
const email = 'customer@example.com';
const timestamp = Date.now(); // current time in milliseconds
const hmacSecret = 'your_mailbox_hmac_secret';
 
const hmac = crypto.createHmac('sha256', hmacSecret)
  .update(`${email}:${timestamp}`)
  .digest('hex');

Python

import hmac
import hashlib
import time
 
email = 'customer@example.com'
timestamp = int(time.time() * 1000)  # current time in milliseconds
hmac_secret = 'your_mailbox_hmac_secret'
 
message = f"{email}:{timestamp}"
signature = hmac.new(
    hmac_secret.encode(),
    message.encode(),
    hashlib.sha256
).hexdigest()

Use the Hash in Your API Request

Include the hash as the emailHash parameter in your session creation request, along with the email and timestamp.

Token Lifetime

The session token is valid for 12 hours. After that, you will need to create a new session.

Session API

On this page