Chat Trigger REST API
      Back to home
      1. Help Center
      2. APIs and SDKs
      3. Chat Trigger REST API

      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/
      newsletter-3729_trigger_API_3x.png
      In this article, we'll explore:

      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

      • If user_id, module_id, is_async, and custom_vars are provided:
        1. The conversation is redirected to the bot's Module with module_id selected.
        2. The custom_vars provided are added to the end user's (user_id) Custom Variable fields.
      • If module_id is not provided:
        1. The conversation is not redirected to any other Module.
        2. The custom_vars provided are added to the end user's (user_id) Custom Variable fields.
      • Key is_async is not mandatory but it needs to be provided and its value must be set to true so that module A -> module B redirection happens.
      • If any of the custom_vars provided in the API request have the same key as any existing end user's Custom Variables, the values are overwritten by the ones in the body of this API request. 

      How to obtain the end user's user_id

      When configuring Webhooks, the following is an example of the JSON's body content for a POST API call that includes the end_user_id:

      Please note, {{certainly.from}} contains the end user's ID.

      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, Certainly 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 Certainly endpoint to drive 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 completes the payment. 
      3. The bot needs to be notified to continue with the flow via the same endpoint.

      Error handling

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

      Response status: 200

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

      Response status: 400

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

      Response status: 400

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

      Response status: 400