VX Agents

API directory · Customer Support

Dixa Conversations & Internal Notes

v1.0.0 · 15 endpoints · 0 connections · shared by vx.ai

Which Dixa conversations are still open for this customer, and what did the team already say about them? Search the inbox with filters, read the message thread and internal notes, then reply, leave a note for a colleague, tag, move it to another queue, or close and reopen it.

Connect this API to an AI agent Browse all specs

What you can do with Dixa Conversations & Internal Notes via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
POST /v1/search/conversations searchConversations Search conversations by text and filters such as status, queue or date
GET /v1/conversations/{conversationId} getConversation Get a conversation's status, channel, assignee and requester
GET /v1/conversations/{conversationId}/messages listMessages List the messages in a conversation
POST /v1/conversations/{conversationId}/messages addMessage Reply to the customer in a conversation
GET /v1/conversations/{conversationId}/notes listInternalNotes List the internal notes on a conversation
POST /v1/conversations/{conversationId}/notes addInternalNote Add an internal note only agents can see
GET /v1/conversations/{conversationId}/tags listConversationTags List the tags on a conversation
GET /v1/queues listQueues List the queues conversations can be routed to
GET /v1/tags listTags List the tags available in the organization
GET /v1/endusers/{userId} getEndUser Get an end user's (customer's) contact details
GET /v1/endusers/{userId}/conversations listEndUserConversations List all conversations of one end user
PUT /v1/conversations/{conversationId}/tags/{tagId} tagConversation Add a tag to a conversation
PUT /v1/conversations/{conversationId}/transfer/queue transferConversation Move a conversation to another queue
PUT /v1/conversations/{conversationId}/close closeConversation Close a conversation
PUT /v1/conversations/{conversationId}/reopen reopenConversation Reopen a closed conversation

Authentication

ApiKeyAuth

API key — sent as the Authorization header

A Dixa API token, sent as the raw value of the Authorization header (no Bearer prefix).

How to get a credential

  1. Sign in to Dixa as an administrator.
  2. Open Settings > Integrations > API tokens (Dixa API section).
  3. Click Add API token, choose the Dixa API version, name it (e.g. VX Agents) and save.
  4. Copy the token; it is shown only once.

Permissions used

Token Operations
Dixa API token (admin-created, organization-wide) all operations: searchConversations, getConversation, listMessages, listInternalNotes, listConversationTags, listQueues, listTags, getEndUser, listEndUserConversations, addInternalNote, addMessage, tagConversation, transferConversation, closeConversation, reopenConversation

Common errors

Status Meaning Fix
401 / 403 Token missing, revoked, or sent with a Bearer prefix Create a new token and send it as the bare header value.
400 Invalid body, e.g. an unknown agentId or queue id Read the message field; look ids up with listQueues or getConversation.
404 Conversation, end user, queue or tag id does not exist Search again to get a current id.
429 Rate limited Wait and retry with backoff.

Store the token as an API key credential in VX Agents; never paste it into chat.

Usage guide

Setup

  • Credential: a Dixa API token (Settings > Integrations > API tokens, created by an admin), stored as an API key credential. It is sent as the bare Authorization value, without Bearer.
  • Worth pinning: the agent's own Dixa agentId (UUID) for replies and notes, so messages are sent in the right name.

Work a conversation

  1. Find it with searchConversations: query {"value": "order 12345"} for text, and/or filters {"strategy": "All", "conditions": [...]}. Each condition is {"field": {"_type": "<Field>", "operator": {"_type": "<Operator>", ...}}}, e.g. open conversations: field Status + operator IsOneOf with values: ["open"]; a queue: QueueId + IsOneOf; created this week: CreationDate + Between with timestampFrom/timestampTo. Page with pageKey.
  2. For one customer, getEndUser then listEndUserConversations.
  3. getConversation, then listMessages and listInternalNotes to read the history; listConversationTags for its tags.
  4. Act, confirming with the user first for anything the customer sees or that changes routing:
    • addInternalNote with message (only agents see it; optional agentId).
    • addMessage as an agent reply: {"_type": "Outbound", "agentId": "<uuid>", "content": {"_type": "Text", "value": "..."}} (Html and Markdown content also work). This is sent to the customer.
    • tagConversation with a tagId from listTags.
    • transferConversation with a queueId from listQueues.
    • closeConversation / reopenConversation (optional userId = acting agent).

Good to know

  • Ids are UUIDs, except conversation ids, which are numbers.
  • Union objects need their _type tag (Outbound, Text, Status, IsOneOf, ...), as in the Dixa examples.
  • Status values: open, pending, closed. Timestamps are ISO 8601 UTC (2026-10-22T09:00:00Z).
  • Anonymizing data, deleting tags and agent or team admin are not part of this spec.

Source: Dixa API v1 reference (https://docs.dixa.io/openapi/dixa-api/v1), checked 2026-10-22.

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “Dixa Conversations & Internal Notes” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.

Related APIs