Trigger Response API endpoint

This endpoint is targeted for use cases where a third-party server needs to send a message to the end user and drive the conversation to a particular Module.

The REST API uses the following path: https://app.certainly.io/actionsvc/trigger-response/

In this article, we'll explore:

Trigger Response (POST)
Example use cases
Error handling

Trigger Response (POST)

Headers

Header	Example	Description
Authorization	Authorization: JWT	Authorization is done via JSON Web Token (JWT)
Content-type	Content-type: application/json	The endpoint will respond by providing the report in JSON format. As such, it's necessary to indicate that the Content-type is application/json.

You can fetch your user token by heading to the Navigation bar and clicking on "user name" when it drops down from the "My Profile" icon at the top right. There, you'll see a field named "public API auth token".

Body

See the example body below

{
  "user_id": "{{certainly.from}}",
  "module_id": 1068935, 
  "wait_time": 0,
  "custom_vars": {},
  "is_async": true
}

user_id String. Should always be "{{certainly.from}}"
module_id Number or null. If provided, the conversation is redirected to the module specified. If you just need to update cvars, you may leave it empty "module_id": null
wait_time Number of seconds. By default, 3 seconds. Non-zero values are needed when doing a Bot-to-Bot transfer to synchronize different threads.
custom_vars Dictionary. Key value pairs, where keys are custom variable names. The names should start with letters. If a variable already exists in the bot, it will be overwritten.
is_async Boolean. It should always be set to true.

Example use cases

Form submission

Bot displays a URL to a form.
End user goes to a new tab to fill in the form, then submits.
With the use of Webhooks, Certainly is able to notify that third-party service of the end user ID.
The third-party server receives the form and needs to notify the bot that the form was submitted in order to continue the conversation flow.
To do so, the third-party server fires an API POST request to a Certainly endpoint to drive conversation X with User Y to moduleID Z.

Payment (Checkout)

Bot refers end user to an external checkout link.
The end user opens the checkout page and completes the payment.
The bot needs to be notified to continue with the flow via the same endpoint.

Error handling

1. If is_async is not provided or not set to true, the request will be successful, but Module A -> Module B redirection will never happen.

{
  "error":[],
  "message":"1"
}

Response status: 200

2. Keys user_id and module_id are mandatory. If either of them is not provided, this error will be triggered:

{
  "message": null,
  "error": "Need a valid json containing user_id and module_id / user_id is mandatory / module_id is mandatory"
}

Response status: 400

3. If user_id or module_id is incorrect, this error will be triggered:

{
  "message": null,
  "error": "Bot user with this id does not exist / module_id not found for the given bot"
}

Response status: 400

4. If the API auth token provided is incorrect, this error will be triggered:

{
  "message": null,
  "error": [{
    "location": "Backend",
    "msg": "Invalid Authentication credentials"
  }]
}

Response status: 400