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.

Configuring Botmaker as a Source

In the 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. Records with activity after this date will be extracted. Note: without Long-term Search, the API only serves the last 7 days of chats and the last 3 days of messages, so older dates are automatically moved forward to that window for those streams.
Long-term Search: Enable historical backfill for chats, messages, sessions, and calls. When enabled, the connector sends long-term-search=true, which Botmaker bills as BI data-source consumption. When disabled, chats only sync the last 7 days and messages the last 3 days; anything older is skipped, with a warning in the run log. Enable it if the source may stay without a successful run for longer than that.

By default, the chats and messages streams only return Botmaker’s recent activity window (the last 7 days for chats, and 3 days for messages). 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 or if the source may stay without a successful run for longer than the short-term window.

2. Select streams

Choose which data streams you want to sync. The available streams are described in the 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, 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.

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

5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

For you to be able to see it on your Catalog, you need at least one successful source run.

Streams and Fields

Available streams

The table below lists every stream and a short description.

Stream	Description
Chats	Chats with their current state, filtered by last-activity window.
Messages	Messages exchanged across chats, filtered by a datetime window.
Sessions	Conversation sessions, filtered by a datetime window.
Calls	Voice and video calls, filtered by a datetime window.
Contacts	Contacts and their channels of communication.
Agents	Agents configured in your Botmaker account.
Channels	Communication channels connected to your account.
Intents	Bot intents defined in your account.
Tickets	Support tickets with their metrics and related data.

Fields by stream

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

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 (null if the contact never wrote).
`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.

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.

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.).

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.

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.

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.

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.

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.

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.

Data Model

The following diagram illustrates the relationships between the core data streams in Botmaker. The arrows indicate the join keys that link the different entities, providing a clear overview of the data structure.

Implementation Notes

Authentication

The connector authenticates against the Botmaker API v2.0 using your access token as the access-token request header.

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.

Empty responses (204 No Content)

Some Botmaker endpoints (like messages) reply with a silent 204 No Content empty body instead of an empty list or an error when a parameter is out of bounds (such as a page size outside the 250-1500 range, or datetimes with microsecond precision). The connector handles this by requesting a fixed page size of 1000, enforcing millisecond precision on datetimes, and gracefully treating any 204 response as a final, empty page.

Long-term search and short-term windows

The windowed endpoints (chats, messages, sessions, and calls) operate within recent activity windows unless Long-term Search is enabled. When disabled, the Botmaker API refuses a start date older than its short-term window (7 days for chats, 3 days for messages). The connector automatically clamps your Start Date forward to this allowable window and skips older records, logging a warning about the unextracted period. Enable Long-term Search (which sends long-term-search=true) to bypass these windows and backfill historical data, but note that Botmaker bills long-term searches as BI data-source consumption.

Skills for agents

Download Botmaker skills file

Botmaker connector documentation as plain markdown, for use in AI agent contexts.

Get started

Context

Activate

Organizations

Workspaces

Resources

Botmaker as a data source

Configuring Botmaker as a Source

1. Add account access

2. Select streams

3. Configure data streams

4. Configure data source

5. Check your new source

Streams and Fields

Available streams

Fields by stream

Data Model

Implementation Notes

Skills for agents

Download Botmaker skills file

​Configuring Botmaker as a Source

​1. Add account access

​2. Select streams

​3. Configure data streams

​4. Configure data source

​5. Check your new source

​Streams and Fields

​Available streams

​Fields by stream

​Data Model

​Implementation Notes

​Skills for agents

Download Botmaker skills file

Configuring Botmaker as a Source

1. Add account access

2. Select streams

3. Configure data streams

4. Configure data source

5. Check your new source

Streams and Fields

Available streams

Fields by stream

Data Model

Implementation Notes

Skills for agents