Trigger 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. In this article, we'll explore:

newsletter-3729_trigger_API_3x.png

Example use cases 

Form Submission

  1. Bot displays a URL to a form.
  2. End user goes to a new tab to fill in the form, then submits.
  3. With the use of Webhooks, Codemonkey is able to notify that third-party service of the end user ID.
  4. 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.
  5. To do so, the third-party server fires an API POST request to a Codemonkey Endpoint to drive the conversation X with User Y to moduleID Z.

Payment (Checkout)

  1. Bot refers end user to an external checkout link.
  2. The end user opens the checkout page and performs the payment. 
  3. The bot needs to be notified to continue with the flow via the same Endpoint.

Endpoint details

Endpoint: https://app.certainly.io/actionsvc/trigger-response/

Method: POST

Headers:

authorization: JWT {userToken}
content-type: application/JSON

You can fetch your {userToken} by heading to the Navigation bar and clicking your user name when it drops down from the "My Profile" avatar icon at the top right. There, you'll see a field named "public API auth token". Copy these contents into your request to replace the {userToken} part of the request.

Body: 

{
"user_id":"<user's id>",
"module_id":"<module-id>",
"custom_vars": {
    "variable1_key": "value",
    "variable2_key": "value",
    ...
    }
}

Behavior

  1. If module_id, user_id and cvars are provided, then the conversation is moved to the module_id and the CVars provided are added to the End User (user_id) Custom Variable fields.
  2. If only user_id and cvars are passed (no module_id provided) then the conversation is NOT redirected to any other module but the CVars are still merged with the BotUser CVars.

Please note: If any of the CVars provided in the API request have the same key as any existing CVar that the End User has, the values are overridden by the values in the body of the API request. 

How to obtain the user_id

When you configure a Webhook, the following is an example of a JSON body of the POST call that hits your Endpoint and includes the end user id in it:

{
"botId": "{{certainly.botId}}",
"moduleId": {{certainly.moduleId}},
"end_user_id": "{{certainly.from}}"
}

The templified value {{certainly.from}} contains the end user id.

Error handling

1. The parameters user_id and module_id are mandatory. If both or any one of the parameters is not passed, you'll receive an error:

Response error:

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

}

Response status: 400

2. If the bot id or the module id passed are incorrect, you'll receive the following error:

Response error:

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

 Response status: 400

3. If the Public API auth token passed is incorrect, you'll receive the following error:

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

 Response status: 400

Was this article helpful?

0 out of 0 found this helpful
Have more questions? Submit a request

Comments (0 comments)

Please sign in to leave a comment.