Initai-js NPM | npm.io

Init.ai JS

A JavaScript library for building browser and Node.js based experiences on top of the Init.ai platform.

This library is in an early phase of development, but is suitable for production use. Please feel free to file any issues or submit a pull request.

Quickstart

Install via npm/yarn

yarn add initai-js

API Client only:

import { createAPIClient } from 'initai-js'

const apiClient = createAPIClient({ token: 'my-token' })

apiClient.sendMessage({ content: 'Hello!', userId: '123' })

Configure a "monitor":

import { createAPIClient, createMonitorClient } from 'initai-js'

const apiClient = createAPIClient({ token: 'my-token' })

createMonitorClient({ apiClient, userId: '123' }).then(monitorClient => {
  monitorClient.on('suggestestions:new', payload => {
    console.log(payload) // {conversation_id: '123', remote_conversation_id: null}
  })
})

Using initai-js

Installation

Using a package manager/loader

You can install initai-js using npm or yarn for use in a project using Webpack, browserify, rollup, etc.

yarn add initai-js

Import the library into your project:

import { createAPIClient } from 'initai-js'

const apiClient = createAPIClient({ token: 'my-token' })

apiClient.sendMessage({ content: 'Hey!', userId: '123' })

Using a script tag

initai-js is not currently distributed via a CDN, however, if you are not using a package manager and would like to, you can build your own file to include in your project.

<html>
  <body>
    <h1>My app</h1>
    <script src="path/to/initai.min.js"></script>
    <script>
      const apiClient = InitAI.createAPIClient({ token: 'my-token' })
      apiClient.sendMessage({ content: 'Hey!', userId: '123' })
    </script>
  </body>
</html>

Using this method, the InitAI namespace is exposed as a global Object.

Browser support

This library is developed for use in modern browsers. Currently, we support:

The latest two versions of Chrome
The latest two versions of Firefox
Safari 10+
Microsoft Edge (latest)

While the library will likely work for more browsers and mobile devices, it is not currently tested for those scenarios.

Node.js support

This library supports Node.js. It is recommended that you use version 8.x or later.

API Client

The API Client is used to communicate with the Init.ai Remote API from a browser.

Initialization

A client instance requires a configuration object that includes a token where the value is that of an API Token which you can get from the Init.ai console.

Init.ai token

Example

import { createAPIClient } from 'initai-js'

const apiClient = createAPIClient({ token: 'API_TOKEN' })

apiClient.sendMessage({ content: 'Hey, friend!', userId: '123' }).then(() => {
  console.log('message sent!')
})

Methods

`sendMessage(messageConfig: MessageConfig): Promise<SendMessageSuccess | SendMessageError>`

`MessageConfig`

An object describing the message to send.

userId: required – The Init.ai database id or the custom remote_id associated with the user
content: required – A string (if contentType is text) or object representing the message content to send
contentType: required - A string representing a valid message type: text, image, or postback-action
- See the docs for more information on using "quick replies" and postback actions.
conversationId: - A string representing the Init.ai database id or the custom remote_conversation_id from an external system such as a CRM. By default, this value will fall back to current.
senderRole: Default end-user – A string representing the message sender: agent, app, end-user

Handling responses

sendMessage returns a Promise which will resolve or reject with the following data:

// Success
{
  id: 'new-message-id',
  sender_role: 'end-user',
  content_type: 'text',
  content: 'Hello!',
  created_at: '2017-06-29T14:57:57.092662Z',
  updated_at: '2017-06-29T14:57:57.092662Z'
}

// Error
{
  status: 500, // HTTP status code
  statusText: 'Server error', // HTTP status message
  message: 'Your message could not be sent at this time'
}

Examples

// Sending a text message
apiClient.sendMessage({
  userId: '123',
  content: 'Hey there!',
  contentType: 'text',
  senderRole: 'agent' 
})

// Sending an image
apiClient.sendMessage({
  userId: '123',
  content: {
    alternativeText: 'Image alt text',
    imageUrl: 'path/to/image/url',
    mimeType: 'image/png'
  },
  contentType: 'image',
})

// Sending a postback action
apiClient.sendMessage({
  userId: '123',
  content: {
    text: 'Order accepted',
    data: { orderNumber: 123, status: 'accepted' },
    stream: 'handleCompletedOrder'
 },
 contentType: 'postback-action',
 senderRole: 'end-user'
})

`fetchMessages(userId: string, conversationId?: string): Promise<FetchMessagesResult>`

Fetch messages for the provided user's current conversation.

`userId`

The Init.ai database id or the custom remote_id associated with the user

`conversationId`

The Init.ai database id or the custom remote_conversation_id from an external system such as a CRM. By default, this value will fall back to current.

Handling responses

fetchMessages returns a Promise which will resolve or reject with the following data:

// Success
{
  messages: [
    {
      id: 'new-message-id',
      sender_role: 'end-user',
      content_type: 'text',
      content: 'Hello!',
      created_at: '2017-06-29T14:57:57.092662Z',
      updated_at: '2017-06-29T14:57:57.092662Z'
    }
  ],
  pagination: {
    page_size: 100,
    current_page_url:
      'https://api.init.ai/v1/users/123/conversations/current/messages?page_before_id=&page_size=100',
    first_page_url:
      'https://s-api.init.ai/v1/users/123/conversations/current/messages?&page_size=100'
  }
}

// Error
{
  status: 500, // HTTP status code
  statusText: 'Server error', // HTTP status message
  message: 'Could not fetch messages for user 123'
}

Examples

apiClient.fetchMessages('123').then(({ messages }) => {
  console.log(messages) // [ ..., {...}, ...]
}).catch(console.log)

`fetchSuggestions(userId: string, conversationId?: string): Promise<SuggestionsResult>`

Fetch the latest message suggestions for the provided user's conversation

`userId`

The Init.ai database id or the custom remote_id associated with the user

`conversationId`

The Init.ai database id or the custom remote_conversation_id from an external system such as a CRM. By default, this value will fall back to current.

Handling responses

fetchSuggestions returns a Promise which will resolve or reject with the following data:

// Success
{
  conversation_id: '123-456',
  suggestions: [
    ...,

    {
      content: { text: 'Some message content' },
      content_type: 'text',
      metadata: {}, // Arbitrary metadata sent with the request
      nlp_metadata: {}, // An Object containing NLP results (auto-suggestions only)
      source_type: 'logic_invocation', // 'api', 'logic_invocation', or 'auto'
      suggestion_type: 'message',
      suggestion_id: '456',
      data: {}, // Data used to populate templated suggestions
    },

    ....
  ]
}

// Error
{
  status: 500, // HTTP status code
  statusText: 'Server error', // HTTP status message
  message: 'Could not fetch suggetions for user 123'
}

Examples

apiClient.fetchSuggestions('123').then(({ suggestions }) => {
  console.log(suggestestions) // [ ..., {...}, ...]
}).catch(console.log)

`triggerInboundEvent(eventConfig: InboundEvent): Promise<TriggerEventResult>`

`InboundEvent`

An object describing the message to send.

userId: required – The Init.ai database id associated with the user
eventType: required – The arbitrary value that will be provided to logic processing.
data: required - An arbitrary Object which you can send along with the request and is available during logic runs.

Handling responses

triggerInboundEvent returns a Promise which will resolve or reject with the following data:

// Success
{
  body: "Event accepted.", 
  error: null
}

// Error
{
  status: 500, // HTTP status code
  statusText: 'Server error', // HTTP status message
  message: 'Your event could not be sent at this time'
}

Examples

// Sending an event
apiClient.triggerInboundEvent({
  userId: '123',
  eventType: 'sample:event',
  data: {
    'key': 'value',
  },
})

Monitor Client

The Monitor Client is used to establish a realtime connection with the Init.ai API to facilitate building rich client-side experiences for conversations.

Initialization

A monitor client instance requires a configuration object that includes:

A userId – The Init.ai database id or the custom remote_id for the current user.
An apiClient – An instance of an Init.ai API Client

The monitor client is instantiated asynchronously which means you will need to use the reference provided via the resolved Promise.

Example

import { createAPIClient, createMonitorClient } from 'initai-js'

const apiClient = createAPIClient({ token: 'my-token' })

createMonitorClient({ apiClient, userId: '123' }).then(monitorClient => {
  // Use `monitorClient`
})

Methods

`on(eventName: string, handler: Function)`

Subscribe to conversation event.

eventName – The name of the event you wish to subscribe to.
- See Events for event names and payload
handler – A function to be called when an event is fired. The payload provided as an argument to this callback will depend on the event itself.

Example usage

const handleSuggestions = payload => console.log('Suggestions:', payload)

monitorClient.on('suggestions:new', handleSuggestions)

`off(eventName?: string, handler?: Function)`

Unsubscribe from a conversation event.

eventName – The name of the event you wish to unsubscribe from
- If this is omitted, all subscriptions will be cancelled
handler – The specific function reference to remove from the callback list
- If this is omitted, all handlers for the given eventName will be removed

Example usage

const handleSuggestions = payload => console.log('Suggestions:', payload)

monitorClient.on('suggestions:new', handleSuggestions)

monitorClient.off('suggestestions:new')

`destroy()`

Destroy the monitorClient instance and remove all subscriptions. This is useful in applications where you may need to swap clients when the current user session expires or changes –– such as a CRM.

Example usage

const handleSuggestions = payload => console.log('Suggestions:', payload)

monitorClient.on('suggestions:new', handleSuggestions)

monitorClient.destroy()

Events

`suggestions:new`

Triggered whenever new suggestions are added to the conversation..

Example payload

{
  conversation_id: '123-456',
  remote_conversation_id: null // Will be a string if remote_conversation_id has been previously set
}

Developing

Install dependencies

yarn

Run in watch mode

yarn dev

The following environment variables are supported:

API_BASE_URL – The protocol, host, and port for your API endpoint. Defaults to https://api.init.ai
PUSHER_APP_KEY – A Pusher application key

Building

To run a "production" build:

yarn build:production

This will build a copy of the library as well as a minified version to /dist

Testing

Run unit tests

yarn test

To use watch mode:

yarn test:watch

Running as a linked module

Depending on your use case, it can often be helpful to develop against a local copy of initai-js. Since the default exports for this library are the artifats built to dist, you will need to use linking and a specific development task to build to dist on change.