Using the API

TWX-Chat offers all Pro Plan users an evolving and secure Developer REST API allowing you interact with TWX-Chat Chatbots and other objects from your Apps. All services are authenticated using a valid OpenAI API Key in the Header that matches your TWX-Chat OpenAI API Key. Details below:

---

Query Chatbot service

This API service allows your Apps to query a TWX-Chat Chatbot just like a visitor to your website would. You can send a Query along with a Chatbot ID to receive AI answers, sources and other metadata. You can even send a thread_id if you wish the service to continue an existing conversation context, otherwise a new one will be generated and returned. All interactions are stored in the Chat Log with a user id of rest_api.

Endpoint

POST /wp-json/twxchat/v1/query-chatbot

Authentication

All requests must include a valid OpenAI API key in the request header. It must match the one you configured in the TWX-Chat General Settings. This prevents unauthorised use from unknown parties:

x-openai-api-key: YOUR_OPENAI_API_KEY

If the header is missing or invalid, the API will return 401 Unauthorized.

Request Parameters

Body (JSON)

Parameter	Type	Required	Description
query	string	✅ Yes	The user’s question or input text for the chatbot.
chatbot_id	string	✅ Yes	The chatbot identifier.
thread_id	string	❌ No	An existing thread ID. Must begin with twxchat_thread_. If omitted, a new one will be generated.
min_similarity	string	❌ No	Example: "75" for 75%. Overrides the chatbot_id’s default similarity threshold.

Example Request

POST https://yourwebsite.com/wp-json/twxchat/v1/query-chatbot
Content-Type: application/json
x-openai-api-key: YOUR_OPENAI_API_KEY

{
  "query": "Am I able to Query the Chatbot from my own App?",
  "chatbot_id": "3",
  "min_similarity": "0.71",
  "thread_id": "twxchat_thread_jh6353FSDvxsacG"
}

Response Fields

Body (JSON)

Field	Type	Description
chatbot_id	string	The ID of the chatbot that handled the query.
kb_source	string	Comma-separated list of knowledge base filters configured in the Chatbot. May be empty.
min_similarity	string	The minimum similarity threshold (as a percentage) applied to match knowledge base entries. Is configured in the Chatbot or provided as a request parameter override.
thread_id	string	The conversation thread ID (e.g., twxchat_thread_abc123) used to store the query and bot response in the Chat Log. If not provided in the request, this is the newly generated one.
answer	string	The chatbot’s response to the user’s query.
sources	array	List of sources that contributed to the answer. Each object contains: • source (string) – URL or identifier of the source document. • similarity_score (float) – Relevance score between 0 and 1. • title (string) – Title of the source document.
messages	array	Previous chat history messages used in the conversation. These have been included in the query as context. Each object has: • role (string) – One of "system", "user", or "assistant". • content (string) – The text content of that message.

Example Response

{
  "chatbot_id": "3",
  "kb_source": "twxchat,product",
  "min_similarity": "75",
  "thread_id": "twxchat_thread_jh6353FSDvxsacG",
  "answer": "Yes, you can query a specific TWX-Chat Chatbot just as any user or visitor would from your own Apps...\n\n",
  "sources": [
    {
      "source": "https://twxchat.twxlabs.au/docs/using-the-api/",
      "similarity_score": 0.7611417363577603,
      "title": "TWX-Chat Using the API"
    }
  ],
  "messages": [
    {
      "role": "system",
      "content": "You're name is Charlie and you are an expert on the TWX-Chat plugin..."
    },
    {
      "role": "user",
      "content": "Does it have an API I can call with my own Apps?"
    },
    {
      "role": "assistant",
      "content": "Yes! TWX-Chat offers a developer API that you can..."
    }
  ]
}

Notes

The messages array provides the full conversation context (system prompt, user input, assistant reply).

Every call creates a chat log entry with user set to "rest_api".

If no thread_id is supplied, a new one will be generated and included in the response.

The sources array (if present) shows which documents/knowledge base entries were most relevant to the response.

---

To Come: Search Knowledge Base

Coming soon, the ability to search your TWX-Chat Knowledge Base directly to utilise sources and content in other Apps.

To Come: Search Chat Log

Coming soon, the ability for your Apps to search and extract TWX-Chat Chatbot conversations to perform your own analysis and gain even deeper insights into your visitor’s requirements.