Methods

These are the methods that can be accessed by the CommonJS require() function. You can make use of the these method to perform different kinds of features like setting new agenda, sending emails, etc.

Example


const _ = require("lodash")
const obj = { 'a': [{ 'b': { 'c': 3 } }] };

_.get(obj, 'a[0].b.c', null);
// => 3

Node.js builtin library

Library	Node.js Documentation
crypto	crypto
http	http
https	https
url	url
querystring	querystring

3rd party library

Library	Description
node-fetch	Node-fetch (`const fetch = require("node-fetch")`) is a library for sending http(s) requests.
moment	Moment (`const moment = require("moment")`) is a library for time related logic. The `moment-timezone` is also supported.
lodash	Lodash (`const _ = require("lodash")`) is a utility library that improves QoL.
xml2js	xml2js (`const { parseString } = require("xml2js")`) is a utility library that parse xml to javascript object.
uuid	uuid (`const { v4: uuidv4 } = require("uuid")`) is a utility library that generate uuid.
stripe	stripe (`const Stripe = require("stripe")`) is Stripe API wrapper.

Custom methods provided by WOZTELL

These methods can be accessed by built-in integration require("woztell-essential-pack")

Example


const { getMember } = require("woztell-essential-pack")
const member = await getMember({
  memberId: this.member._id
})

DB Notes

WOZTELL use mongoDB as database. For any DB methods below, please see the mongoDB CRUD Operations documentation for reference. More specifically, you should refer to the mongoDB's "Query Document" section for the filter parameter. For the patch and withModifier parameters, you should refer to mongoDB's "Change a Document" section, where the patch object will be set as $set if withModifier is false, while setting withModifier to true will let you customize the update modifier, or to replace the document.

A findAndModify method is an atomic operation, ie. the "find" and "modify" happens at the same time. It is preferred to doing a "find" operation and a "modify" operation separately. It is used to prevent a critical action from happening more than once, even if the user spams the input or the external service sends multiple events at the same time, accidentally or purposefully. To achieve this, a filter and patch pair should be set so that the same entry won't be found after being modified. The example in findAndModifyMember shows how it works.

withModifier: false
patch = {
  key: value
}

update = {
  $set: {
    key: value
  }
}

withModifier: true
patch = {
  $addToSet: {
    key: value
  }
}

update = {
  $addToSet: {
    key: value
  }
}

fetchDataFromDataSource

The method fetchDataFromDataSource() is used to fetch data from data source.

Example

fetchDataFromDataSource({ collectionName: string, dataSourceId: string , filter: object, count: boolean, sortBy: object })

Parameter

Name	Type	Description
collectionName	string	Either collectionName or dataSourceId. Collection name
count	boolean	`Default false`. Status of this method is performing count feature only
dataSourceId	string	Either collectionName or dataSourceId. Data source ID
filter	object	`Optional` Filter criteria. Shares the same method as MongoDB query. Please see MongoDB for further reference
sortBy	object	`Optional` Shares the same method as MongoDB query. Please see MongoDB for further reference

Response

[
  {
    "id": string
    // ...
  },
  // ...
]

fetchDistinctDataFromDataSource

The method fetchDistinctDataFromDataSource() is used to fetch distinct data(i.e. the column of the data source table) from data source.

Example

fetchDistinctDataFromDataSource({ collectionName: string, dataSourceId: string , filter: object, count: boolean, sortBy: object })

Parameter

Name	Type	Description
collectionName	string	Either collectionName or dataSourceId. Collection name
count	boolean	`Default false`. Status of this method is performing count feature only
dataSourceId	string	Either collectionName or dataSourceId. Data source ID
key	string	The column you wish to fetch from data source
filter	object	`Optional` Filter criteria. Shares the same method as MongoDB query. Please see MongoDB for further reference

Response

[
  value of key,
  // ...
]

fetchGeoNearFromDataSource

The method fetchGeoNearFromDataSource() is used to fetch geographical data from data source.

Example

fetchGeoNearFromDataSource({ collectionName: string, data: object, dataSourceId: string })

Parameter

Name	Type	Description
collectionName	string	Either collectionName or dataSourceId. Collection name
data	object	Geo data
dataSourceId	string	Either collectionName or dataSourceId. Data source ID

Response

[
  {
    "id": string
  },
  // ...
]

countDataSource

The method countDataSource() is used to count the information about the present channel.

Example

countDataSource({ collectionName: string, dataSourceId: string, filter: object })

Parameter

Name	Type	Description
collectionName	string	Either collectionName or dataSourceId. Collection name
dataSourceId	string	Either collectionName or dataSourceId. Data source ID
filter	object	`Optional` Filter criteria. Shares the same method as MongoDB query. Please see MongoDB for further reference

Response

400 // A number

patchDataToDataSource

The method patchDataToDataSource() can be used to patch data to data source. In this call, the patch object will be formatted in this way in the data source table: each object becomes a new row; object key becomes column and object value becomes the value.

Example

patchDataToDataSource({ collectionName: string, dataSourceId: string, filter: object, patch: object, options: object, multi: boolean, withModifier: boolean })

Parameter

Name	Type	Description
collectionName	string	Either collectionName or dataSourceId. Collection Name
dataSourceId	string	Either collectionName or dataSourceId. Data Soruce ID
filter	object	`Optional` Filter criteria. Shares the same method as MongoDB query. Please see MongoDB for further reference
multi	boolean	`Optional` Whether update multiple fields
options	object	Options for the request
patch	object	The field and data that needs to be patched
withModifier	boolean	`Default false` Status the method contains modifier

Response

{
  "matched": number
  "modified": number
  "inserted": number
  "deleted": number
}

findAndModifyDataFromDataSource

The method findAndModifyDataFromDataSource() is used to find and modify a data entry in a Data Source.

Parameter

Name	Type	Description
dataSourceId	string	Data Source ID
filter	object	Filter to find the data entry
patch	object	Object to be patched to the data entry
withModifier	boolean	Default false. see DB Notes for more details
sortBy	object	Optional. Order to sort the data entries. Note: only the first data entry after sorting is found and modified by this method.
option	object	Optional. Use `{ "new": true }` to get the modified data entry. Please refer to mongoDB's Collection Methods for other options.

Example

findAndModifyDataFromDataSource({
  dataSourceId: "a12345678901234567890123_coupon",
  filter: {
    location: "HK",
    memberId: null,
  },
  patch: {
    memberId: "m12345678901234567890123",
    deliveredAt: 1601481600000,
  },
  withModifier: false,
  sortBy: {
    priority: 1,
  },
  option: {
    new: true,
  }
})

Response

Name	Type	Description
ok	number	`1` for successful call
value	object	The data entry object found. If `option.new` is `true`, the modified data entry will be returned. Otherwise, the original data entry will be returned. Return `null` if no matched data entry is found.

{
  ok: 1,
  value: {
    _id: "d12345678901234567890123",
    location: "HK",
    couponCode: "1234",
    priority: 0,
    memberId: "m12345678901234567890123",
    deliveredAt: 1601481600000,
    createdAt: 1577808000000,
    updatedAt: 1601481600000
  }
}

upsertDataToDataSource

The method upsertDataToDataSource() will upsert data entries in the Data Source. If _id exists in the data object, it will be upserted in the Data Source, ie. if a data entry with the same _id exists, the entry will be updated, else, a new data entry will be inserted. Otherwise, a new data entry will be inserted.

Parameter

Name	Type	Description
dataSourceId	string	Data Source ID
data	object or [object]	Data to be updated or inserted

Example

upsertDataToDataSource({
  dataSourceId: "a12345678901234567890123_coupon",
  data: [{
    _id: "d12345678901234567890123", // exists in Data Source
    location: "HK",
    couponCode: "0123",
    priority: 1,
  }, {
    _id: "d12345678901234567890124", // not exists in Data Source
    location: "KLN",
    couponCode: "0124",
    priority: 2,
  }, {
    location: "NT",
    couponCode: "0125",
    priority: 3,
  }]
})

Response

Name	Type	Description
result	object	`Result` object

Result

Name	Type	Description
_docsIds	object	`DocsIds` object
matched	number	Number of matched entries
modified	number	Number of modified entries
inserted	number	Number of inserted entries
deleted	number	`0`

DocsIds

Name	Type	Description
updated	[string]	Array of `_id` of updated entries
inserted	[string]	Array of `_id` of inserted entries
upserted	[string]	Array of `_id` of inserted entries with `_id` provided

{
  result: {
    _docsIds: {
      updated: ["d12345678901234567890123"],
      inserted: ["d12345678901234567890125"],
      upserted: ["d12345678901234567890124"]
    },
    matched: 1
    modified: 1
    inserted: 2
    deleted: 0
  }
}

newAgenda

The method newAgenda() can be used to create new agenda. Please refer to here for reference on the Agenda system.

Parameter

Name	Type	Description
memberId	string	WOZTELL Member ID
treeId	string	Tree ID
nodeCompositeId	string	Node Composite ID
nextRunAt	number	Override `pattern`. Either `nextRunAt` or `pattern` is required. Timestamp for executing the agenda (Unix epoch time in milliseconds). The `moment.js` library can be used, eg. `moment().add(5, "minutes").valueOf()` gives the timestamp of 5 minutes from now.
pattern	string	Either `nextRunAt` or `pattern` is required. CRON Pattern of the agenda. If you wish to check the CRON pattern, you can use Crontab Guru
runUntil	number	Required if `pattern` is used. The agenda will be executed following the `pattern` until the `runUntil` timestamp.
priority	number	Optional. The priority of the agenda. Agenda with the smaller `priority` number will be executed first.
meta	object	Optional. The data associated with the agenda. This object can be accessed by `this.agendaMeta` when the agenda is executed.
replace	boolean	Default false. Set as `true` to replace agendas of the same member with the same `tag`.
tag	string	Required if `replace` is `true`. Agenda tag

Example

newAgenda({
  memberId: "m12345678901234567890123",
  treeId: "t12345678901234567890123",
  nodeCompositeId: "abcdefghijklmnop",
  nextRunAt: 1609430400000,
  priority: 1,
  meta: {
    testing: true
  },
  replace: true,
  tag: "testing-agenda"
})

Response

The agenda object created will be returned.

{  
  _id: "ag2345678901234567890123",
  app: "a12345678901234567890123",
  channel: "c12345678901234567890123",
  member: "m12345678901234567890123",
  tree: "t12345678901234567890123",
  nodeCompositeId: "abcdefghijklmnop",
  nextRunAt: 1609430400000,
  priority: 1,
  meta: {
    testing: true
  },
  tag: "testing-agenda",
  completed: false,
}

updateAgenda

The method updateAgenda() can update the agenda in the database.

Example

updateAgenda({ memberId: string, meta: object, nextRunAt: number, nodeCompositeId: string, priority: number, pattern: string, replace: boolean, runUntil: number, tag: string, treeId: string })

Parameter	Type	Description
memberId	string	WOZTELL Member ID
meta	object	The data wish to send inside the agenda
nodeCompositeId	string	Node Composite ID
nextRunAt	number	Time for running the next agenda in milliseconds. This property will override the `pattern` property
pattern	string	CRON Pattern of the agenda. If you wish to check the CRON pattern, you can use Crontab Guru
priority	number	The priority of the agenda
runUntil	number	Timestamp for running the agenda until it stops
replace	boolean	`Default false`. Whether the input is replaced
treeId	string	Tree ID
tag	string	Member tag

Response

{
  "_docsIds": {
    "updated": array<string>
  },
  "_docs": array<object>
  "modified": number
}

deleteMemberAgenda

The method deleteMemberAgenda() is used to delete member agenda by WOZTELL member ID.

Example

deleteMemberAgenda({ memberId: string, tag: string })

Parameter

Name	Type	Description
memberId	string	WOZTELL Member ID
tag	string	Specific agenda name

Response

{
  "clientMutationId": string
}

sendEmail

The method sendEmail() can be used to send email through Amazon SES service from no-reply@sanuker.com. This method returns nothing from our API.

Example

const params = {
  Destination: {
    CcAddresses: ["sample@sanuker.com", "sample2@sanuker.com"],
    ToAddresses: ["sameple3@sanuker.com", "sameple4@sanuker.com"]
  },
  Message: {
    Body: {
      Html: {
        Charset: "UTF-8",
        Data: "HTML_FORMAT_BODY"
      },
      Text: {
        Charset: "UTF-8",
        Data: "TEXT_FORMAT_BODY"
      }
    },
    Subject: {
      Charset: 'UTF-8',
      Data: 'Test email'
    }
  }
}

sendEmail(params)

Parameter	Type	Description
destination	object	The email address you want to send and CC to.
message	object	The subject and message(in either HTML or Text format) you want to have in the email.

uploadFileToS3

The method uploadFileToS3() can upload file to our S3 server. Please note that this method return nothing.

Example

stripe({ url: string, options: object, channel: object, filename: string, contentType: string })

Parameter	Type	Description
url	string	URL of the file
options	object	Option of the request
channel	string	Channel Object
filename	string	Name of the file
contentType	string	Content type of the file

getMember

The method getMember() is used to get the information about the present member from its WOZTELL member ID.

Example

getMember({ memberId: string })

Parameter

Name	Type	Description
memberId	string	WOZTELL Member ID

Response

{
  "_id": string
  "_version": number
  "app": string
  "botId": string
  "botMeta": object
  "channel": string
  "createdAt": timestamp
  "etag": string
  "externalId": string
  "firstName": string
  "gender": string
  "meta": object
  "platform": string
  "profile": object
  "tags": array<object>
  "updatedAt": timestamp
}

patchMembers

The method patchMembers() can be used to patch data to members.

Example

patchMembers({ channel: object, memberId: string, filter: object, patch: object, withModifier: boolean })

Parameter

Name	Type	Description
channel	object	Channel object
filter	object	`Optional` Filter criteria. Shares the same method as MongoDB query. Please see MongoDB for further reference
memberId	string	WOZTELL Member ID
patch	object	The field and data that needs to be patched
withModifier	boolean	`Default false` Status the method contains modifier

Response

{  
  "result": {
    "_id": string
    "createdAt": timestamp
    "updatedAt": timestamp
    "profile": object
    // ...
  }
}

findAndModifyMember

The method findAndModifyMember() is used to find and modify a member.

Parameter

Name	Type	Description
filter	object	Filter to find the member
patch	object	Object to be patched to the member
withModifier	boolean	Default true. see DB Notes for more details
sortBy	object	Optional. Order to sort the members. Note: only the first member after sorting is found and modified by this method.
option	object	Optional. Use `{ "new": true }` to get the modified member. Please refer to mongoDB's Collection Methods for other options.

Example

findAndModifyMember({
  filter: {
    firstName: "John",
    "meta.checked": false,
  },
  patch: {
    "meta.checked": true,
  },
  withModifier: false,
  sortBy: {
    _id: -1,
  },
  option: {
    new: true,
  }
})

Response

Name	Type	Description
ok	number	`1` for successful call
member	object	The Member object found. If `option.new` is `true`, the modified member will be returned. Otherwise, the original member will be returned. Return `null` if no matched member is found.

{
  ok: 1,
  member: {
    _id: "m12345678901234567890123",
    app: "a12345678901234567890123",
    channel: "c12345678901234567890123",
    externalId: "1234567890",
    firstName: "John",
    lastName: "Doe",
    botMeta: {
      liveChat: false,
      subscribe: true,
      tempData: {},
      nodeCompositeId: "abcdefghijklmnop",
      tree: "t12345678901234567890123"
    },
    meta: {
      checked: true,
    },
    platform: "custom",
    tags: [],
    createdAt: 1577808000000,
    updatedAt: 1601481600000
  }
}

updateMember

The method updateMember() can the update member's information in the database.

Example

updateMember({ member: object })

Parameter	Type	Description
member	object	Member object

Response

{
  "_docsIds": {
    "updated": array<string>
  },
  "_docs": object
  "modified": number
}

getChannel

The method getChannel() is used to get the information about the present channel.

Example

getChannel({ channelId: string })

Parameter

Name	Type	Description
channelId	string	The channel ID that you have

Response

{
  "_id": string,
  "app": string,
  // ...
}

redirectMemberToNode

The method redirectMemberToNode() is used to redirect a member to a node. The node will then be executed for the member according to the redirectOptions. For usage in WOZTELL API, you may also refer to the WOZTELL API documentation.

Parameter

Name	Type	Description
memberId	string	WOZTELL Member ID
channelId	string	Channel ID of the Member
treeId	string	Tree ID
nodeCompositeId	string	Node composite ID
redirectOptions	object	Optional. `RedirectOptions` Object
meta	object	Optional. The data associated with the node. This object can be accessed by `this.agendaMeta` when the node is executed.

RedirectOptions

Name	Type	Description
runPreAction	boolean	Default true. Whether the Pre Actions of the node is exectued.
sendResponse	boolean	Default true. Whether the Responses of the node is sent.
runPostAction	boolean	Default true. Whether the Post Actions of the node is exectued.

Example

redirectMemberToNode({
  memberId: "m12345678901234567890123",
  channelId: "c12345678901234567890123",
  treeId: "t12345678901234567890123",
  nodeCompositeId: "abcdefghijklmnop",
  redirectOptions: {
    runPreAction: false,
    sendResponse: true,
    runPostAction: true
  },
  meta: {
    testing: true
  }
})

Response

Name	Type	Description
ok	number	`1` for successful call
member	string	WOZTELL Member ID
sendResults	[object]	Array of `NodeSendResult` Object. The first entry represents the send results of the node. Any subsequence entries represent the send results of the nodes redirected from the original node.

NodeSendResult

Name	Type	Description
ok	number	`1` for successful call
member	string	WOZTELL Member ID
result	[object]	Array of `SendResult` Object. Each entry represents the send result of a response in the node.

SendResult

Name	Type	Description
result	object	Platform specific result to the actual send request. The example below shows the result from Facebook.
messageEvent	object	Message Event object. Please refer here for more details.
chatId	string	WOZTELL Chat ID

{
  ok: 1,
  member: "m12345678901234567890123",
  sendResults: [
    {
      ok: 1,
      member: "m12345678901234567890123",
      result: [
        {
          result: {
            recipient_id: "1234567812345678",
            message_id: "xxxxxxxxxxxxxxxx"
          },
          messageEvent: {
            from: "8765432187654321",
            to: "1234567812345678",
            data: {
              url: "https://s3.ap-southeast-1.amazonaws.com/radiate-admin/59bba4275a304100055da5bc/hello-min.gif",
              attachment_id: "2345678923456789",
              transform: ""
            },
            type: "IMAGE",
            timestamp: 1604160000000,
            messageId: "xxxxxxxxxxxxxxxx"
          },
          chatId: "ch2345678901234567890123"
        },
        {
          result: {
            recipient_id: "1234567812345678",
            message_id: "xxxxxxxxxxxxxxxx"
          },
          messageEvent: {
            from: "8765432187654321",
            to: "1234567812345678",
            data: {
              text: "Hello, I am WOZTELL the Dog 🐶 ",
              transform: ""
            },
            type: "TEXT",
            timestamp: 1604160000001,
            messageId: "xxxxxxxxxxxxxxxx"
          },
          chatId: "ch2345678901234567890124"
        },
        {
          result: {
            recipient_id: "1234567812345678",
            message_id: "xxxxxxxxxxxxxxxx"
          },
          messageEvent: {
            from: "8765432187654321",
            to: "1234567812345678",
            data: {
              transform: "",
              quickReplies: [
                {
                  content_type: "text",
                  title: "Yes ❤️",
                  payload: "ONBOARDING"
                },
                {
                  content_type: "text",
                  title: "No ☠️",
                  payload: "MAIN_MENU"
                }
              ],
              text: "My master Sanuker can help you make bots on different platforms with my help, would you like to make one?"
            },
            type: "QUICK_REPLIES",
            timestamp: 1604160000002,
            messageId: "xxxxxxxxxxxxxxxx"
          },
          chatId: "ch2345678901234567890125"
        }
      ]
    }
  ]
}

sendResponse

The method sendResponse() can send response in different channels.

Example

sendResponse({ channel: object, channelId: string, memberId: string, response: object })

Parameter	Type	Description
channel	object	Channel object
channelId	string	Channel ID
member	object	Member object
memberId	array	A set of WOZTELL member IDs
response	object	Response object. The structure of the response object can be referred to the Message Event documentation for further reference.

Response

// Facebook
{
  "result": object
  "messageEvent": object
}

// WhatsApp
{
  "result": object
  "messageEvent": object
}

// Slack
{
  "ok": boolean
  "channel": string
  "ts": timestamp
  "message": object
}

// Teams
{
  "result": object
  "messageEvent": object
}

// Webchat
{
  "result": object
  "messageEvent": object
}

// WeChat
{
  "msgType": string
  "url: string
  "image": object
  "text": object
  "video": object
  "title": string
  "description": string
  "news" string
}

Node.js builtin library​

3rd party library​

Custom methods provided by WOZTELL​

DB Notes​

fetchDataFromDataSource​

fetchDistinctDataFromDataSource​

fetchGeoNearFromDataSource​

countDataSource​

patchDataToDataSource​

findAndModifyDataFromDataSource​

Parameter​

Example​

Response​

upsertDataToDataSource​

Parameter​

Example​

Response​

Result​

DocsIds​

newAgenda​

Parameter​

Example​

Response​

updateAgenda​

deleteMemberAgenda​

sendEmail​

uploadFileToS3​

getMember​

patchMembers​

findAndModifyMember​

Parameter​

Example​

Response​

updateMember​

getChannel​

redirectMemberToNode​

Parameter​

RedirectOptions​

Example​

Response​

NodeSendResult​

SendResult​

sendResponse​

Node.js builtin library

3rd party library

Custom methods provided by WOZTELL

DB Notes

fetchDataFromDataSource

fetchDistinctDataFromDataSource

fetchGeoNearFromDataSource

countDataSource

patchDataToDataSource

findAndModifyDataFromDataSource

Parameter

Example

Response

upsertDataToDataSource

Parameter

Example

Response

Result

DocsIds

newAgenda

Parameter

Example

Response

updateAgenda

deleteMemberAgenda

sendEmail

uploadFileToS3

getMember

patchMembers

findAndModifyMember

Parameter

Example

Response

updateMember

getChannel

redirectMemberToNode

Parameter

RedirectOptions

Example

Response

NodeSendResult

SendResult

sendResponse