API Usage

EngageOne Communicate offers a REST API that gives programmatic access to the actions available in the Communicate web application, such as blacklisting email addresses, adding assets to the Asset Library and creating campaigns.

The following APIs are available:

Type Description Swagger documentation
Public API Endpoints for actions that do not require authentication, such as adding an email address to the unsubscribe list or verifying an email address for use when sending emails. https://docs.api.communicate.engageone.co/public.html
Private API Endpoints for actions that require authentication because they access the company's campaigns, communications, templates and assets. To use the Private API, you must provide an authentication token as part of the header. https://docs.api.communicate.engageone.co/private.html
Users API Endpoints for login and authentication. https://docs.api.communicate.engageone.co/users.html
Document Channel API Endpoints for actions connected with document channel, includes templates and communications operations as well as PDF generation. https://docs.api.communicate.engageone.co/document-channel.html
Chat Channel API Endpoints for actions connected with chat channel, includes templates and communications operations. https://docs.api.communicate.engageone.co/chat-channel.html
Note: Public and private APIs are regional. Please select the correct endpoint for your Communicate team.

To use the APIs, you need to:

  1. Get the client credentials for your company account.
  2. Get an authentication token (JWT) using the User Services API /authenticate endpoint.

  3. Invoke the Private API with your authentication headers.

Get client credentials

In order to invoke the endpoints in the Private API, you require a set of client credentials. You can obtain this from the Account Settings screen. You need to be an administrator to access this page. For details of creating client credentials, see Client credentials.

Once credentials have been added, hover over the CustomerID, ClientID and Secret and select Copy to Clipboard to copy these to the clipboard.

In particular, keep the Secret token for use later — the Secret is only shown once (the customer ID and client ID will not change). If you lose the Secret token, you will need to generate a new one.

Note: If client credentials already exist and you don't know the Secret token, click Regenerate Secret to get a new token. You will then need to update any existing integration that uses the Secret token.

Get authentication token

In order to call the endpoints in the Private API, you need to provide two authentication headers:

Header Details
PB-Customer-Id The ID of the Communicate company you are acting on. This is the name of the company prefixed with eocm-, and with spaces replaced by hyphens. This is case sensitive.
Authorization Takes the form of Bearer {token} where {token} is a JWT token obtained with the client credentials calling the /authenticate endpoint in the Users API.

Remove API access

To remove API access, delete the client credentials.

REST example

This example shows how EngageOne Converse can use the EngageOne Communicate API endpoints to trigger email sending in Communicate.

In this Converse example, the EOCM Token and EOCM Send Email interactions invoke the Communicate API:

Note: For details of interactions, including action interactions, in Converse, see the EngageOne Converse documentation.

Get Chat History

In Converse, this interaction configures the bot to make a transcript of the messages sent between the bot and the user available in the current session. It is this transcript that will be emailed to the user.

EOCM Token

In Converse, this interaction configures the bot to request a machine to machine authentication token from Communicate. The action interaction is configured like this:

Action type REST
Endpoint https://usersapi.communicate.engageone.co/authenticate
Method POST
Body Passes the credentials for your Communicate account. You obtain these from the Company Management page in Communicate. For example:
{
  "client_id": "1234567@communicate.pb.com",
  "secret": "secret",
  "customer_id": "customerID"
}
Variable Name Name of the variable that stores the authorization token returned by Communicate in the session.
EOCM Send Email

In Converse, this action interaction configures the bot to trigger Communicate to send an email to the user set in the body of the request.

Action type REST
Endpoint https://api.us-east-1.communicate.engageone.co/campaigns/ mycampaign/transactional
Method POST
Authorization The authorization token acquired from Communicate. For example:Bearer {my-variable}
Headers Your Communicate customer ID:
  • Header Name is always PB-Customer-Id
  • Value is your customer ID
Body The data required by the communication in Communicate. The data must conform to the schema of the data source selected for the communication. For example:
{
    "communication": "Thanks",
    "dataset": [{
        "name": "Henry",
        "email": "an-email-address",
        "chatHistory": "{{chatHistory}}"
    }],
    "email_json_path": "$[*].email",
    "sender": "eocommunicate-dev@pb.com",
    "subject": "Thanks for contacting us today",
    "ignore_missing_fields": true,
    "project": "my-project"
}