Chaskiq Plugins API

Requests & Responses

The Chaskiq Apps works by sending you POST requests to the URLs you provide and reply to them properly with JSON objects.

There's several different types of requests that we will (or optionally may) send to you. The types available are: Initialize, Configure & Submit.

Initialize

The Initialize request is triggered when a Agent:

  • Adds your app into to a conversation reply
  • Adds your app into an Chat flow
  • Adds your app into a Message
  • Adds your app on to the Messenger Home
  • Adds your app to the conversation details Inbox

Initialize Request

The initialize request is the action that will be called just after an agent has configured the plugin (added to conversation, inbox or home) the initialize action is the view that will be displayed to the visitors.

Initialize request example:

{ kind: 'configure',
  ctx: 
   { values: { key: 'value' },
     field: null,
     location: 'home',
     lang: 'en',
     app: { key: 'ABGBUo3gqaBc_sz2GgE57g', name: 'test app' },
     current_user: 
      { id: 2,
        kind: 'agent',
        display_name: '',
        avatar_url: 'https://www.gravatar.com/avatar/bf47b813b0de4867a015fd4b54ac2fb4?d=https://ui-avatars.com/api//128' } },
  package: 
   { id: 20,
     app_package_id: 19,
     app_id: 1,
     settings: { access_token: '09B00kBfwiE_OoM1ZO9XiYohoM5uH_9TXEFGncAtuSE' },
     state: null,
     created_at: '2020-10-27T05:43:53.303Z',
     updated_at: '2020-10-27T05:43:53.303Z',
     external_id: null } }

Initialize response

the initialize response will contain a definitions object

{
    definitions: [ ... ]
}

You have to set the initialize URL from the app configuration details

Configure

Agents can optionally configure an app before the initialize request is sent to insert the app. If you provide a URL to receive this request, it will trigger when a agent:

  • Adds your app into to a conversation reply
  • Adds your app into an Chat bot
  • Adds your app into a Message
  • Adds your app on to the LiveChat Home
  • Interacts with components which have an associated submit action

Configure Request

The first request we send will allow you to know the workspace where this is happening, the admin who will be configuring the app, and additional context such as where this will be added once complete.

For subsequent requests whereby an admin has interacted with a component with a submit action, the request payload will contain the same details with current_canvas, input_values and the component_id also present. This allows you to understand what component the request came from, see what the value of any input was, action anything in your codebase, and then respond knowing what canvas was previously shown beforehand.

kind: 'configure',
ctx:
    { lang: 'es',
        app: {
            key: 'le-vTjBW83OYOgGmmtK_-w',
            name: 'Some App'
        },
    current_user: { 
        id: 2,
        kind: 'agent',
        display_name: 'Miguel michlsoijoijoij',
        avatar_url: '[https://www.gravatar.com/avatar/bf47b813b0de4867a015fd4b54ac2fb4?d=https://api.adorable.io/avatars/130/bf47b813b0de4867a015fd4b54ac2fb4.png](https://www.gravatar.com/avatar/bf47b813b0de4867a015fd4b54ac2fb4?d=https://api.adorable.io/avatars/130/bf47b813b0de4867a015fd4b54ac2fb4.png)'
    },
    { 
        values: {},
        field:{ 
            type: 'button',
            label: 'Click ME!!!!',
            style: 'primary',
            id: 'url_button',
            action: [Object]
        },
    },
    package:{
        id: 8,
        app_package_id: 17,
        app_id: 1,
        settings: { api_key: 'aaaaa' },
        state: null,
        created_at: '2020-09-21T00:04:25.989Z',
        updated_at: '2020-09-21T00:04:25.989Z',
        external_id: null 
    }
}

Configure response

We either expect:

A definitions object which will replace the previous UI that was visible until the agent interacted with your app.

A results object which will end the configuration and trigger the initialize request to be sent. There will be a results object in the payload showing your key-value pairs from the results object.

{
    kind: 'initialize',
    results: { "key": "value" },
    definitions: defaultButton
}

You have to set the configure URL from the app configuration details

Submit

The Submit request is triggered when:

A component with a submit action is clicked from visitors

Example component with a Submit Action

{ 
  action: {
    "type": "submit"
  }
}
{ 
  action: {
    "type": "submit"
  }
}

You have to set the submit URL from the app configuration details

Submit Request

The format of the request we send is similar to the Initialize request but contains a values which is the values sent from the actions and field which is the component that triggered the action. This allows you to understand what component the request came from, see what the value of any input was.

← IntroLive API →