SDK - Chatbot

SDK Functions

This section gathers the main features available for integration with Tatodesk, including SDK resources, sending messages via WhatsApp and SMS, as well as operations related to notifications, CRM and session metadata. Below, you will find an interactive menu that facilitates navigation between topics, allowing quick access to descriptions and usage examples for each feature.

Click the topics below to quickly navigate between subjects:

• Sending texts and multimedia;

• Sending multimedia with Headers - Creating URL;

• Dynamic construction of buttons;

• Registering and capturing variables in the session;

• Channels;

• Registering Additional Information;

• CRM;

• Ticket;

• Contact Center;

• ChatBot;

• Marketing.

Sending texts and multimedia

These functions are used to interact with the SDK and send formatted messages of different types, such as text, image, file, video, audio and link.

sdk.send.text("your text")

sdk.send.image(url)

sdk.send.file(url)

sdk.send.video(url)

sdk.send.audio(url)

sdk.send.link("Text","Url")

Sending multimedia with Headers - Creating URL

sdk.chatbot.externalMedia(method, url, options, body)

Here a call is made to an external API and the parameters (method, url, options and body) are used to request data from that API.

Example of use case:

  const method = 'GET'
  
  const url = `https://www.clientbackend.xx.gov.br/certificate/pdf idProfessional=${idProfessional}`
  
  const options = {
    headers: {
      'Authorization': token,
      'Application': 4
    }
  }
  
  const res = await sdk.chatbot.externalMedia(method, url, options, body)
  { chatbotExternalMedia, error } = res

  chatbotExternalMedia: String | null  (Access link to the external media) 
 error: Error | null

In this example, using the GET method (data request), a request is made for an external link passing a parameter through the URL, and through the 'options' the headers are included with authorization information.

The constant 'res' makes the API call, which has the requested external link.

The result of the API call can have two properties: 'chatbotExternalMedia', which can be a string or null. If the response is successful, the link will be returned. Otherwise, the property 'error', which is an error object or null, will contain information about the error that occurred.

Dynamic construction of buttons

const buttonMessage = `Title above the buttons`

const buttons = [
  {
    title: "First button",
    payload: "First button",
    without_bold: true
  },
  {
    title: "Second button",
    payload: "Second button",
    without_bold: true
  }
]

sdk.send.buttons(buttonMessage, buttons)

The buttons function is called from the SDK send object and receives two arguments. The first is a string, which defines the title displayed above the buttons. The second is an array of objects, where each object represents a button.

Each object may contain the following properties:

• title: text displayed on the button;

• payload: value that identifies the button when it is clicked;

• without_bold: boolean value (true or false) that defines whether the text will be displayed without bold;

Registering and capturing variables in the session

await sdk.session.setAttribute(key,value)

let myVariable = await sdk.session.getAttribute(key)

await sdk.session.deleteAttribute(key)

In sdk.session.setAttribute(key, value), the function setAttribute is called on the session object of the SDK to set an attribute in the session, where key represents the attribute key and value the value associated with that key.

Meanwhile, in sdk.session.getAttribute(key), the function getAttribute is called on the same object to retrieve the stored value for the given key. The returned result is stored in the variable myVariable.

Finally, in sdk.session.deleteAttribute(key), the function deleteAttribute is used to remove an attribute from the session, identified by the key key.

Thus, one expression sets, another retrieves and another deletes specific user information during the session.

Get Request

const config = {
  headers: {
    'Agreement':agreement,
    'Origin':origin,
    'Authorization': authorization
  }
}
const res = await sdk.net.get(`https://yourdomain.com`,config)

In the example, the object config contains the property headers, which gathers three headers composed of key and value pairs:

• Agreement: key 'Agreement' and the variable value agreement;

• Origin: key 'Origin' and the variable value origin;

• Authorization: key 'Authorization' and the variable value authorization.

The constant res stores the result of the request, and the use of await causes the code to wait for the completion of the get call before proceeding with execution. Thus, the program only continues after the request finishes and the server response is received.

Post Request

The object

const config = {
  headers: {
    'Agreement':agreement,
    'Origin':origin,
    'Authorization': authorization
  }
}

has the property config , which contains three headers defined as key and value pairs: headerskey and value: key and value:

• Agreement: key 'Agreement' and the variable value agreement;

• Origin: key 'Origin' and the variable value origin;

• Authorization: key 'Authorization' and the variable value authorization.

Response

const req = {
  field_name: composed_value,
  field_name_2: field_value_2
}

Here an object is created that has the properties field_name and field_name_2, each receiving a corresponding value of the same name.

Request

const res = await sdk.net.post(`https://yourdomain.com`, req, config);

In sdk.net.post(https://yourdomain.com`, req, config) the function post of the net object of the sdk is being used to make an HTTP POST request to the url.

Channels

sdk.channel.isWebchat()
sdk.channel.isWhatsapp()
sdk.channel.isInstagram()
sdk.channel.isTelegram()
sdk.channel.isFacebookMessenger()

The SDK functions are used to identify the channel in use. Each of them returns a boolean value (true or false), indicating whether the specific channel is active.

Registering Additional Information

Chatbot Info:

await sdk.chatbot.addInfo(key, value)

Digital Service Info:

await sdk.contactCenter.setDataItem(key, value)

const zapObj = sdk.session.getMetadataWhatsapp()

await sdk.chatbot.addInfo('WHATSAPP_NUMBER', zapObj['phone'])

The function getMetadataWhatsapp is called on the session of the SDK to capture information from the current WhatsApp session and store the result in the variable zapObj.

Then, the function addInfo is called on the chatbot of the SDK, passing two arguments: the key 'WHATSAPP_NUMBER' and the corresponding value zapObj['phone'].

CRM

const person = await sdk.crm.getPersonByText("81900000000")
{
  person: {
    ID: string
  },
  customFields: [
    {
      key: string,
      value: string
    }
  ],
  tags: [
    {
      name: string
    }
  ]
}

Performs a query by phone number via before proceeding with execution. and returns an object with the properties:

• person — basic person data (e.g.: ID);

• customFields — array of custom fields { key, value };

• tags — array of tags { name }.

const person = {
  firstName:"person's name",
  emails:["[email protected]"],
  phones:["81900000000"],
  tags:["WHATSAPP-OPT-IN"]
}

const p = await sdk.crm.createPerson(person)

has the property person is created with the properties firstName, emails, phones and tags, which store the information of the person to be registered. Then, the method createPerson receives this object as an argument, using its data to create a new person record in the CRM.

Adding Tag in CRM

await sdk.crm.addTag(PERSON_ID,"TAG_NAME")

The method addTag is called on the crm object of the sdk, receiving as parameters PERSON_ID and TAG_NAME. It uses this information to add the specified tag to the record of the corresponding person in the CRM.

Adding Custom Fields in CRM

const persons = await sdk.crm.listCRMPersonsByCustomField("KEY",value)

In the constant persons, the object sdkis called, which returns a list of people stored in the crm. The parameters "KEY" and value are used in the search to filter records according to the provided custom field.

Example Full Structure of the Object

[
  {
    "person": {
      "ID"
    },
    "customFields": [
      {
        "key": "string",
        "value": "string"
      }
    ],
    "tags": [
      {
        "name": "string"
      }
    ]
  }
]

This structure contains the personobject, which has the property ID of type string. The customFields is an array that stores objects with the properties key and value, representing the custom fields of the person. Finally, the array tags contains objects with the property name, which indicates the tags associated with the person.

Ticket

Create Ticket

Possibilities to create tickets through the builder SDK, as an alternative to magic forms.

Component Structure - Example:

const forms = []

forms.push({ key: "EMAIL", value: email })
forms.push({ key: "REGISTRATION", value: registration })
forms.push({ key: "CPF/CNPJ", value: document })
forms.push({ key: "NAME", value: fullName })
forms.push({ key: "PROPERTY_ADDRESS", value: address })
forms.push({ key: "PHONE", value: phone })

if (proof) {
  forms.push({ key: "PROPERTY_DOCUMENT", value: proof })
}

forms.push({ key: "IDENTITY", value: documentImage })
forms.push({ key: "SELFIE", value: customerImage })
forms.push({ key: "PROPERTY_WATER_BILL", value: billImage })

if (paidBillImage) {
  forms.push({ key: "RECENT_PAYMENT_PROOF", value: paidBillImage })
}

forms.push({ key: "STATE_YOUR_RELATIONSHIP_WITH_PROPERTY", value: relation })

const res = await sdk.ticket.create(
  organizationID,
  projectID,
  departmentID,
  description,
  attendanceTypeIDs,
  forms,
  formID,
  2
)

In the code, the constant forms is an array that starts empty and receives objects through the pushmethod. Each object has the properties key and value, for example, { key: "EMAIL", value: email }, adding the field "EMAIL" with its respective value. The if is used to include optional fields, such as { key: "PROPERTY_DOCUMENT", value: proof }, only when the variable proof is defined.

The constant res stores the return of the create of the ticket object of the sdkfunction, which receives several parameters (organizationID, projectID, departmentID, description, attendanceTypeIDs, forms, formID, 2) and creates a new ticket in the system with the provided data.

Contact Center

Skipping the magic form when being redirected to the human agent:

await sdk.contactCenter.skipForm()

Skipping the group, subgroup, specialty, subspecialty, area and subarea:

await sdk.contactCenter.skipQuestion()

Skipping the custom service hours:

await sdk.contactCenter.skipAttendanceGroupOpeningHour()

The await indicates that each of these calls is asynchronous, that is, the code waits for their execution before proceeding. Each method is responsible for skipping a specific step of the flow:

• skipForm() → skips the magic form, sending the service directly to the human.

• skipQuestion() → ignores the categorization questions (group, subgroup, specialty, area, etc.).

• skipAttendanceGroupOpeningHour() → skips the verification of custom service hours.

Thus, the flow automatically proceeds to the next step, making the process faster and avoiding that the user needs to fill out or select information already known by the system.

Assigning information to the service when being redirected to the human agent:

Key - Value Keys available for use:

• CPF_CNPJ

• NAME

await sdk.contactCenter.setFormItem("CPF_CNPJ", cpf)

The function setFormItem("CPF_CNPJ", cpf) is used to set an item of the form during the service. The await command indicates that the call is asynchronous, that is, the code will wait for the operation to complete before proceeding.

has the property sdk contains the contactCenterobject, responsible for operations related to human service. In the example above, the field "CPF_CNPJ" is set with the value stored in the variable cpf, showing this information in the agent's queue.

Getting session variables:

await sdk.session.getMetadataWebchat()

The function getMetadataWebchat() is used to obtain the metadata of the current Webchat channel session. The await command indicates that the call is asynchronous, that is, the code will wait for the data to be returned before continuing execution.

has the property sdk contains the session, responsible for storing and providing information related to the active session. As a result, the contextual information of the ongoing service in the Webchat is returned.

Example of use case:

const metadataWebchat = sdk.session.getMetadataWebchat();

phoneParam = metadataWebchat.browser.queryParams["phone"];

On the first line, the function getMetadataWebchat() is used to capture the Webchat session metadata, storing the result in the constant metadataWebchat. On the second line, the value associated with the key "phone" is accessed from metadataWebchat.browser.queryParams and stored in the constant phoneParam.

Getting information by name:

The functions below perform asynchronous calls to fetch specific information within the contactCenterobject, present in the main object sdk.

In all cases, the passed parameter is a string representing the entity name you want to locate.

• Gets the Department by name:

await sdk.contactCenter.getDepartmentByName(departmentName)

• Gets the Attendance Group by name:

await sdk.contactCenter.getAttendanceGroupByName(groupName)

• Gets the Group Specialization by name:

await sdk.contactCenter.getGroupSpecializationByName(specializationName)

• Gets the Subspecialization by name:

await sdk.contactCenter.getSubSpecializationByName(subSpecializationName)

• Gets the Area by name:

await sdk.contactCenter.getAreaByName(areaName)

• Gets the Subarea by name:

await sdk.contactCenter.getSubAreaByName(subAreaName)

In all methods, the await indicates that the code execution will wait for the asynchronous call to return before proceeding. The expected return is an object containing the information of the located entity.

Setting Service Information

The functions below are used to set the identifiers (ID) of the entities related to a service within the contactCenterobject, present in the main object sdkobject. Each function receives a parameter that represents the ID of the entity that will be associated with the service.

• Sets the department of the service:

await sdk.contactCenter.setDepartmentID(departmentID)

• Sets the attendance group:

await sdk.contactCenter.setAttendanceGroupID(attendanceGroupID)

• Sets the group's specialization for the attendance:

await sdk.contactCenter.setAttendanceGroupSpecializationID(groupSpecializationID)

• Sets the attendance subspecialization:

await sdk.contactCenter.setSubspecializationID(subSpecializationID)

• Sets the service area:

await sdk.contactCenter.setAreaID(areaID)

• Sets the service subarea:

await sdk.contactCenter.setSubareaID(subAreaID)

All functions use the await to await the asynchronous execution of the call. These definitions are used to correctly categorize and route the service within the Contact Center framework.;

ChatBot

Adding Additional Information:

await sdk.chatbot.addInfo(key, value)

The function addInfo(key, value) adds custom information to the chatbot session. The parameter key represents the identifying key of the information, and value the value associated with that key. The call is made asynchronously, awaiting execution using await.

Marketing

Obtaining information (metadatas) from single notifications and WhatsApp campaigns:

The functions below are used to retrieve additional data (metadata) related to WhatsApp campaigns and notifications by accessing the object mkt inside the sdk. Both perform asynchronous calls, awaiting the return using await.

await sdk.mkt.getWhatsappNotificationMetadatas()

Returns the metadata of single notifications sent via WhatsApp.

wait sdk.mkt.getWhatsappMktCampaignTargetAudienceMetadatas()

Returns the metadata of the target audience of a WhatsApp marketing campaign.

These functions allow access to additional information about the active session or campaign, useful for monitoring and analyzing the performance of communications via WhatsApp.