Skip to main content

APIs for Custom Channel

Once you've configured your custom channel and distributed a flow via your custom channel, you would want to start the flow for your users and pipe their responses for further processing.

To achieve to this, you can use our REST endpoints for custom channels.

REST APIs

Start a new session​

API Reference

This API is used to start a new session for your users

Request​

  • URL - https://stage-askribe-askribe-ohlibf5r4a-el.a.run.app/api/v1/consumer/custom-channel/start
  • Request Method - POST
  • Headers - "Content-Type": "application/json"
  • Body
    • askribeKey
      • Type: String
      • Required
      • Obtain the API key required to connect with Askribe servers from the Settings section in your Askribe flow dashboard.
    • configId
      • Type: String
      • Required
      • This is the ID of your API / SDK Distribution. This can be obtained from your flow's distribution list
    • context
      • Type: Map<String, VariableData>
      • Optional
      • Description: Pass a list of Key-Value pairs to be substituted in the flow
    • contactId
      • Type: String
      • Optional
      • Description: Pass your user's id. This can be obtained by using our CDP APIs
    • language
      • Type: String
      • Optional
      • Description: Use this parameter to set the language of the flow

Response​

  • Response Type - application/json
  • Body
    • customChannelResponseDTOType
      • Type: Enum
      • Possible Values
        • START_FLOW_RESPONSE - Sent when the session was started successfully and you need to render the block for your users
        • START_FLOW_LINK - Sent when the session was started successfully and you need to render a link for your users to start the flow. You can get the link from the content field.
        • FLOW_SCHEDULED - Sent when the session has been successfully scheduled for the future
        • ERROR - Sent when an error has occurred. You can get more details about the error from content field
    • sessionId
      • Type: String
      • Description: This is the ID of the session. Use this for all further communications with our system
    • nodeId
      • Type: String
      • Description: This is the ID of the block. It is only sent when the type of response is START_FLOW_RESPONSE.
    • newEditNodeType
      • Type: Enum
      • Description: This is the type of block. It is only sent when the type of response is START_FLOW_RESPONSE.
      • Possible Values
        • STATEMENT
        • TEXT_INPUT
        • NUMERIC_INPUT
        • URL_INPUT
        • EMAIL_INPUT
        • PHONE_NUMBER_INPUT
        • DATE_TIME
        • UPLOAD
        • LISTEN - Note that the content would be empty for this case
        • OPTIONS - Two additional parameters isMultiple and options will be sent for this
    • content
      • Type: String
      • Description: This is the main content of the block
    • isMultiple
      • Type: String
      • Description: Sent when newEditNodeType = OPTIONS. Indicates whether the user is allowed to select multiple options
    • options
      • Type: List<{content: string, buttonId: string}>
      • Description: Sent when newEditNodeType = OPTIONS. This contains the data to display interactive buttons / options to your user

Get next block​

API Reference

After you have started a new session using the previous API and rendered a block for your users, you might want to render the next block.

Request​

  • URL - https://stage-askribe-askribe-ohlibf5r4a-el.a.run.app/api/v1/consumer/custom-channel/next
  • Request Method - POST
  • Headers - "Content-Type": "application/json"
  • Body
    • askribeKey
      • Type: String
      • Required
      • Obtain the API key required to connect with Askribe servers from the Settings section in your Askribe flow dashboard.
    • sessionId
      • Type: String
      • Required
      • Description: This is the ID of the session. You can get it from the response of the /start request
    • nodeId
      • Type: String
      • Required
      • Description: This is the ID of the block. You can get it from the response of the previous request
    • response
      • Type: String
      • Optional
      • Description: This is the response given by the user. Use it when the block type is
        • TEXT_INPUT
        • NUMERIC_INPUT
        • URL_INPUT
        • EMAIL_INPUT
        • PHONE_NUMBER_INPUT
        • DATE_TIME
        • LISTEN - (In case of textual response)
        • OPTIONS - (In case of isMultiple = false)
    • responses
      • Type: List<String>
      • Optional
      • Description: This is the response given by the user when block type is OPTIONS and isMultiple = true
    • imageUrls videoUrls fileUrls audioUrls
      • Type: List<String>
      • Optional
      • Description: This is the response given by the user when block type is UPLOAD or block type is LISTEN and response is non-textual

Response​

  • Response Type - application/json
  • Body
    • customChannelResponseDTOType
      • Type: Enum
      • Possible Values
        • NEXT_BLOCK - The request was successful and you need to render the new block for your users
        • ERROR - Sent when an error has occurred. You can get more details about the error from content field
        • END_FLOW - Sent when the session has ended
    • All the other parameters are the same as /start request

Exit flow​

API Reference

Use this API to exit out of a flow

Request​

  • URL - https://stage-askribe-askribe-ohlibf5r4a-el.a.run.app/api/v1/consumer/custom-channel/exit
  • Request Method - POST
  • Headers - "Content-Type": "application/json"
  • Body
    • askribeKey
      • Type: String
      • Required
      • Obtain the API key required to connect with Askribe servers from the Settings section in your Askribe flow dashboard.
    • sessionId
      • Type: String
      • Required
      • Description: This is the ID of the session. You can get it from the response of the /start request

Response​

  • Response Type - application/json
  • Body
    • customChannelResponseDTOType
      • Type: Enum
      • Possible Values
        • END_FLOW - The request was successful and the flow has ended
        • ERROR - Sent when an error has occurred. You can get more details about the error from content field

Get languages​

API Reference

You can get all languages of the flow using this API

Request​

  • URL - https://stage-askribe-askribe-ohlibf5r4a-el.a.run.app/api/v1/consumer/custom-channel/get-languages
  • Request Method - POST
  • Headers - "Content-Type": "application/json"
  • Body
    • askribeKey
      • Type: String
      • Required
      • Obtain the API key required to connect with Askribe servers from the Settings section in your Askribe flow dashboard.
    • sessionId
      • Type: String
      • Required
      • Description: This is the ID of the session. You can get it from the response of the /start request

Response​

  • Response Type - application/json
  • Body
    • customChannelResponseDTOType
      • Type: Enum
      • Possible Values
        • LIST_LANGUAGES - The request was successful. You will get the response in languages field
        • ERROR - Sent when an error has occurred. You can get more details about the error from content field
    • languages
      • Type: List<{id: string, name: string}>
      • Description: Contains the name and id of the languages present in the flow

Set language​

API Reference

You can set the language of a session using this API

Request​

  • URL - https://stage-askribe-askribe-ohlibf5r4a-el.a.run.app/api/v1/consumer/custom-channel/set-language
  • Request Method - POST
  • Headers - "Content-Type": "application/json"
  • Body
    • askribeKey
      • Type: String
      • Required
      • Obtain the API key required to connect with Askribe servers from the Settings section in your Askribe flow dashboard.
    • sessionId
      • Type: String
      • Required
      • Description: This is the ID of the session. You can get it from the response of the /start request
    • languageId
      • Type: String
      • Required
      • Description: This is the ID of the language. You can get it from the response of the /get-languages request

Response​

  • Response Type - application/json
  • Body
    • The response is same as /next request

Transformation

Upon calling the /start, /next or /set-language API, you might receive a JSON which contains the block that you want to render for your users.

You can use simple programming constructs to achieve the transformation. As an example, we'll show you how to transform the response obtained from Askribe to render the blocks in Intercom's Canvas Kit

Example code​


const response = getResponseFromAskribe(); // Call the appropiate API using this response

let intercomResponse = {};

if (response != null) {
  const {
    customChannelResponseDTOType,
    newEditNodeType,
    isMultiple,
    content,
    options,
    nodeId
  } = response;

  if (
    customChannelResponseDTOType === "START_FLOW_RESPONSE" ||
    customChannelResponseDTOType === "NEXT_BLOCK"
  ) {
    if (newEditNodeType === "STATEMENT") {
      intercomResponse = {
        type: "text",
        text: content
      };
    } else if (
      [
        `TEXT_INPUT`,
        -`NUMERIC_INPUT`,
        -`URL_INPUT`,
        -`EMAIL_INPUT`,
        -`PHONE_NUMBER_INPUT`
      ].includes(newEditNodeType)
    ) {
      intercomResponse = {
        type: "input",
        id: nodeId,
        label: content
      };
    } else if (newEditNodeType === "OPTIONS") {
      if (isMultiple) {
         intercomResponse = {
          type: "checkbox",
          id: nodeId,
          label: content,
          options: options.map((it)=>({{
              type: "option",
              id: it.buttonId,
              text: it.content
            }}))
        };
      } else {
        intercomResponse = {
          type: "dropdown",
          id: nodeId,
          label: content,
          options: options.map((it)=>({{
              type: "option",
              id: it.buttonId,
              text: it.content
            }}))
        };
      }
    }
  }
} else {
  console.log("An error has occurred");
}