> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Botmaker as a data source

> Bring Botmaker conversations, contacts, and agent activity to Nekt.

Botmaker is a conversational platform for WhatsApp, Instagram, Messenger, and other channels, with bot automation and human-agent handoff. This connector extracts your chats, messages, sessions, calls, contacts, and agent data from the Botmaker API v2.0 and lands them in your Nekt Catalog as queryable tables.

<img height="50" src="https://mintlify.s3.us-west-1.amazonaws.com/nekt/assets/logo/logo-botmaker.png" />

## Configuring Botmaker as a Source

In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Botmaker option from the list of connectors.

Click **Next** and you'll be prompted to add your access.

### 1. Add account access

You'll need a Botmaker API access token. Generate it in Botmaker under **Configuration → Integrations → API** (the Credentials tab). Once you have it, add the account access, then click **Next**.

The following configurations are available:

* **Access Token**: Botmaker API access token, sent in the `access-token` request header.
* **Start Date**: The earliest date you want to extract data from.
* **Long-term Search**: Enable historical backfill for chats, messages, sessions, and calls.

<Warning>
  By default, the chats, messages, sessions, and calls streams only return Botmaker's recent activity window. To backfill older history from your Start Date, enable **Long-term Search**. Botmaker bills long-term searches as BI data-source consumption, so enable it only when you need the full history.
</Warning>

### 2. Select streams

Choose which data streams you want to sync. The available streams are described in the [Streams and Fields](#streams-and-fields) section below. Select the streams and click **Next**.

### 3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table, and the type of sync.

* **Layer**: choose between the existing layers on your catalog.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You can add a **prefix** to all tables at once.
* **Sync Type**: you can choose between INCREMENTAL and FULL\_TABLE.
  * Incremental: only new or updated records since the last successful run are extracted (available for chats, messages, sessions, calls, and tickets).
  * Full table: every run fetches the full current state of the selected stream.

Once you are done configuring, click **Next**.

### 4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters.

To define your [Trigger](https://docs.nekt.com/get-started/core-concepts/triggers), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).

Optionally, you can define some additional settings:

* Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated.
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**.

Once you are ready, click **Next** to finalize the setup.

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

<Warning>For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.</Warning>

# Streams and Fields

Below you'll find all available data streams from Botmaker and their corresponding fields:

<AccordionGroup>
  <Accordion title="Chats">
    Chats with their current state, filtered by last-activity window. Incremental on `lastUserMessageDatetime`.

    | Field                         | Type     | Description                                                    |
    | :---------------------------- | :------- | :------------------------------------------------------------- |
    | `chat_id`                     | String   | Botmaker chat id.                                              |
    | `channel_id`                  | String   | Channel id of the chat.                                        |
    | `contact_id`                  | String   | Contact id (for example, the user's phone number on WhatsApp). |
    | `creationTime`                | DateTime | When the chat was created.                                     |
    | `lastSessionCreationTime`     | String   | Start time of the last session.                                |
    | `externalId`                  | String   | External identifier for the chat user.                         |
    | `firstName`                   | String   | User's first name.                                             |
    | `lastName`                    | String   | User's last name.                                              |
    | `country`                     | String   | User's country.                                                |
    | `email`                       | String   | User's email.                                                  |
    | `whatsAppWindowCloseDatetime` | DateTime | When the WhatsApp 24-hour window closes.                       |
    | `variables`                   | String   | JSON-encoded chat variables.                                   |
    | `tags`                        | Array    | Tags applied to the chat.                                      |
    | `queueId`                     | String   | Queue the chat is assigned to.                                 |
    | `agentId`                     | String   | Agent currently assigned.                                      |
    | `onHoldAgentId`               | String   | Agent the chat is on hold for.                                 |
    | `lastUserMessageDatetime`     | DateTime | Timestamp of the last user message.                            |
    | `listMessagesURL`             | String   | API URL to list this chat's messages.                          |
    | `isBanned`                    | Boolean  | Whether the user is banned.                                    |
    | `isTester`                    | Boolean  | Whether the user is a tester.                                  |
    | `isBotMuted`                  | Boolean  | Whether the bot is muted for this chat.                        |
  </Accordion>

  <Accordion title="Messages">
    Messages exchanged across chats, filtered by a datetime window. Incremental on `creationTime`.

    | Field                 | Type     | Description                                                             |
    | :-------------------- | :------- | :---------------------------------------------------------------------- |
    | `id`                  | String   | Message id.                                                             |
    | `creationTime`        | DateTime | When the message was created.                                           |
    | `from`                | String   | Sender of the message.                                                  |
    | `agentId`             | String   | Agent who sent the message, if any.                                     |
    | `queueId`             | String   | Queue associated with the message.                                      |
    | `content`             | Object   | Message content (type, text, buttons, media, location, call, template). |
    | `encryptionParams`    | Object   | Encryption metadata, when applicable.                                   |
    | `sessionCreationTime` | DateTime | Start time of the session the message belongs to.                       |
    | `sessionId`           | String   | Session id.                                                             |
    | `chat_id`             | String   | Botmaker chat id.                                                       |
    | `channel_id`          | String   | Channel id of the chat.                                                 |
    | `contact_id`          | String   | Contact id of the chat.                                                 |
  </Accordion>

  <Accordion title="Sessions">
    Conversation sessions, filtered by a datetime window. Incremental on `creationTime`.

    | Field           | Type     | Description                                                |
    | :-------------- | :------- | :--------------------------------------------------------- |
    | `id`            | String   | Session id.                                                |
    | `creationTime`  | DateTime | When the session started.                                  |
    | `startingCause` | String   | What triggered the session.                                |
    | `chat`          | Object   | Chat the session belongs to.                               |
    | `messages`      | Array    | Session messages (only when included by the API).          |
    | `events`        | Array    | Session events (only when included by the API).            |
    | `aiAnalysis`    | Object   | AI analysis of the session (summary, quality score, etc.). |
  </Accordion>

  <Accordion title="Calls">
    Voice and video calls, filtered by a datetime window. Incremental on `creationDatetime`.

    | Field              | Type     | Description                                   |
    | :----------------- | :------- | :-------------------------------------------- |
    | `id`               | String   | Call id.                                      |
    | `chat_id`          | String   | Botmaker chat id.                             |
    | `channel_id`       | String   | Channel id of the chat.                       |
    | `contact_id`       | String   | Contact id of the chat.                       |
    | `agentId`          | String   | Agent involved in the call.                   |
    | `creationDatetime` | DateTime | When the call record was created.             |
    | `startDatetime`    | DateTime | When the call started.                        |
    | `endDatetime`      | DateTime | When the call ended.                          |
    | `recording`        | Object   | Call recording (id and url).                  |
    | `type`             | String   | Call type.                                    |
    | `participants`     | Array    | Call participants and their join/leave times. |
  </Accordion>

  <Accordion title="Contacts">
    Contacts and their channels of communication.

    | Field            | Type   | Description                        |
    | :--------------- | :----- | :--------------------------------- |
    | `id`             | String | Contact id.                        |
    | `firstName`      | String | Contact's first name.              |
    | `lastName`       | String | Contact's last name.               |
    | `birthday`       | String | Contact's birthday.                |
    | `pictureUrl`     | String | Profile picture URL.               |
    | `language`       | String | Preferred language.                |
    | `country`        | String | Country.                           |
    | `companyId`      | String | Associated company id.             |
    | `jobTitle`       | String | Job title.                         |
    | `phoneNumbers`   | Array  | Phone numbers (value and label).   |
    | `emails`         | Array  | Email addresses (value and label). |
    | `addresses`      | Array  | Addresses (value and label).       |
    | `websites`       | Array  | Websites (value and label).        |
    | `instagramIds`   | Array  | Linked Instagram ids.              |
    | `facebookIds`    | Array  | Linked Facebook ids.               |
    | `twitterIds`     | Array  | Linked Twitter ids.                |
    | `notes`          | Array  | Free-text notes.                   |
    | `chats`          | Array  | Chats linked to this contact.      |
    | `whatsappBsuids` | Array  | Linked WhatsApp business user ids. |
  </Accordion>

  <Accordion title="Agents">
    Agents configured in your Botmaker account.

    | Field            | Type     | Description                   |
    | :--------------- | :------- | :---------------------------- |
    | `id`             | String   | Agent id.                     |
    | `email`          | String   | Agent's email.                |
    | `name`           | String   | Agent's name.                 |
    | `alias`          | String   | Display alias.                |
    | `isOnline`       | Boolean  | Whether the agent is online.  |
    | `status`         | String   | Agent status.                 |
    | `role`           | String   | Agent role.                   |
    | `queues`         | Array    | Queues the agent belongs to.  |
    | `slots`          | Integer  | Concurrent chat slots.        |
    | `priority`       | String   | Assignment priority.          |
    | `groups`         | Array    | Groups the agent belongs to.  |
    | `additionalInfo` | String   | JSON-encoded additional info. |
    | `creationTime`   | DateTime | When the agent was created.   |
  </Accordion>

  <Accordion title="Channels">
    Communication channels connected to your account.

    | Field       | Type    | Description                                                |
    | :---------- | :------ | :--------------------------------------------------------- |
    | `id`        | String  | Channel id.                                                |
    | `platform`  | String  | Channel platform (for example, whatsapp, instagram\_chat). |
    | `active`    | Boolean | Whether the channel is active.                             |
    | `name`      | String  | Channel name.                                              |
    | `webhookId` | String  | Associated webhook id.                                     |
  </Accordion>

  <Accordion title="Intents">
    Bot intents defined in your account.

    | Field      | Type    | Description                              |
    | :--------- | :------ | :--------------------------------------- |
    | `id`       | String  | Intent id.                               |
    | `name`     | String  | Intent name.                             |
    | `bot`      | Object  | Bot the intent belongs to (id and name). |
    | `topics`   | Array   | Topics associated with the intent.       |
    | `triggers` | Array   | Triggers that activate the intent.       |
    | `active`   | Boolean | Whether the intent is active.            |
  </Accordion>

  <Accordion title="Tickets">
    Support tickets. Incremental on `creationTime`.

    | Field                     | Type     | Description                                   |
    | :------------------------ | :------- | :-------------------------------------------- |
    | `id`                      | String   | Ticket id.                                    |
    | `businessId`              | String   | Business id.                                  |
    | `ticketCode`              | String   | Human-readable ticket code.                   |
    | `state`                   | String   | Ticket state.                                 |
    | `lastStateModification`   | String   | When the state last changed.                  |
    | `creationTime`            | DateTime | When the ticket was created.                  |
    | `lastModificationBy`      | String   | JSON-encoded last modifier.                   |
    | `subject`                 | String   | Ticket subject.                               |
    | `content`                 | String   | Ticket content.                               |
    | `contentFormat`           | String   | Format of the content.                        |
    | `searchableContent`       | String   | Searchable content.                           |
    | `companyId`               | Integer  | Company id.                                   |
    | `authorId`                | Integer  | Author id.                                    |
    | `assignedTo`              | String   | JSON-encoded assignee.                        |
    | `followBy`                | Array    | User ids following the ticket.                |
    | `waitingQueueIds`         | Array    | Queues waiting on the ticket.                 |
    | `waitingAssignationSince` | String   | Since when the ticket is awaiting assignment. |
    | `assignedQueueId`         | String   | Queue the ticket is assigned to.              |
    | `firstAnswer`             | String   | First answer timestamp.                       |
    | `resolveDate`             | String   | Resolution date.                              |
    | `finishedSlasMetrics`     | String   | JSON-encoded SLA metrics.                     |
    | `attachments`             | Array    | Ticket attachments.                           |
    | `chatIds`                 | String   | JSON-encoded related chat ids.                |
    | `fieldValues`             | Array    | Custom field values.                          |
  </Accordion>
</AccordionGroup>

## Implementation Notes

<AccordionGroup>
  <Accordion title="Authentication">
    The connector authenticates against the Botmaker API v2.0 using your access token as the `access-token` request header.
  </Accordion>

  <Accordion title="Pagination">
    Most streams paginate by following the absolute `nextPage` URL returned in each response. The tickets stream uses `offset`/`limit` pagination based on the response's `total` count.
  </Accordion>

  <Accordion title="Long-term search and billing">
    The chats, messages, sessions, and calls endpoints only return Botmaker's recent activity window unless **Long-term Search** is enabled, which sends `long-term-search=true`. Botmaker bills long-term searches as BI data-source consumption, so enable it only when you need to backfill history from your Start Date.
  </Accordion>
</AccordionGroup>

## Skills for agents

<Snippet file="agent-skills-intro.mdx" />

<Card title="Download Botmaker skills file" icon="wand-magic-sparkles" href="/sources/botmaker.md">
  Botmaker connector documentation as plain markdown, for use in AI agent contexts.
</Card>