Deep Chat message endpoint

POST

/wp-json/wp2tutor-bot/deepchat/v1/chat/{channel_id}

curl --request POST \
  --url https://example.com/wp-json/wp2tutor-bot/deepchat/v1/chat/123 \
  --header 'Content-Type: application/json' \
  --header 'X-Wp2tutor-Bot-Secret: <X-Wp2tutor-Bot-Secret>' \
  --data '{ "messages": [ { "role": "user", "text": "Hello" } ] }'

Deep Chat connect contract. Public POST: cookie/nonce are not checked. Header X-Wp2tutor-Bot-Secret must match meta wp2tutor_bot_dc_secret. CORS is open (request Origin or *); the dc_origins whitelist is not applied in this controller. Request body is {messages: [{role, text}, …]} (widget shape). PHP requires a non-empty messages array and at least one role=user message with non-empty text. Success body is {text} only (string from LlmAnswerService / ChatProxyService). Layer errors are {error} with a human-readable string, not WP_Error {code,message,data} and not Telegram/VK machine codes. Limit: 20 requests / 60 s per key deepchat|{IP}|{channel_id} (RequestRateLimiter). WP2Tutor Ai module must be enabled.

Authorizations

• botSecret

Parameters

Path Parameters

channel_id

required

integer

CPT wp2tutor_channel post ID of type deepchat. Required (path (?P<channel_id>\d+)). Metabox URL and connect example: …/deepchat/v1/chat/{post_id}. Not the widget session id. <= 0, not wp2tutor_channel, or type is not deepchat — 404 {error}.

Example

123

Request Body^required

Media typeapplication/json

object

messages

required

Deep Chat widget messages. Required and non-empty, otherwise 400. PHP scans from the end for the first role=user with non-empty text; the LLM gets a window of the last ~12 turns (user / ai|assistant / system).

Array<object>

object

role

Role in the widget chat: user, ai or assistant, system. Not a WordPress user role. Inbound parse needs at least one user.

string

text

Widget turn text. PHP skips user messages with empty text.

string

Example

{
  "messages": [
    {
      "role": "user",
      "text": "Hello"
    }
  ]
}

Responses

200

Model reply. Body is {text} only — PHP string $reply. No upstream extra fields.

Media typeapplication/json

object

text

required

Assistant reply text. The only 200 field: PHP WP_REST_Response( [ 'text' => $reply ], 200 ).

string

Example

{
  "text": "Short assistant reply"
}

400

Empty body, not JSON, no messages array, no user text (Empty request body. / Invalid JSON. / messages array is required. / No user message found.), or Could not build a prompt from messages. Body {error}.

Media typeapplication/json

object

error

required

Human-readable string (__() / WP_Error message / LLM text). PHP: {error: $message}. Not a Telegram/VK machine code and not {code,message,data}.

string

Example

{
  "error": "messages array is required."
}

401

Invalid secret. — header empty or does not match the channel secret (channel found and secret is set in meta).

Media typeapplication/json

object

error

required

Human-readable string (__() / WP_Error message / LLM text). PHP: {error: $message}. Not a Telegram/VK machine code and not {code,message,data}.

string

Example

{
  "error": "Invalid secret."
}

403

Forbidden. — reserved for DualRest/capability rejection if the request is treated as an authenticated cookie session (this endpoint is secret-gated and normally returns 401 for a bad secret).

Media typeapplication/json

object

error

required

Human-readable string (__() / WP_Error message / LLM text). PHP: {error: $message}. Not a Telegram/VK machine code and not {code,message,data}.

string

Example

{
  "error": "Forbidden."
}

404

Channel not found. — no wp2tutor_channel post or type is not deepchat.

Media typeapplication/json

object

error

required

Human-readable string (__() / WP_Error message / LLM text). PHP: {error: $message}. Not a Telegram/VK machine code and not {code,message,data}.

string

Example

{
  "error": "Channel not found."
}

429

Too many requests. Please try again later. — more than 20 requests in 60 s from this IP for this channel.

Media typeapplication/json

object

error

required

Human-readable string (__() / WP_Error message / LLM text). PHP: {error: $message}. Not a Telegram/VK machine code and not {code,message,data}.

string

Example

{
  "error": "Too many requests. Please try again later."
}

500

Failed to encode prompt. — wp_json_encode of the prompt did not return a string.

Media typeapplication/json

object

error

required

Human-readable string (__() / WP_Error message / LLM text). PHP: {error: $message}. Not a Telegram/VK machine code and not {code,message,data}.

string

Example

{
  "error": "Failed to encode prompt."
}

503

Channel disabled (Channel disabled.), channel secret not set (Channel secret is not configured.), Ai module unavailable/disabled, LLM failure, or empty model reply. Body {error} with the PHP message.

Media typeapplication/json

object

error

required

Human-readable string (__() / WP_Error message / LLM text). PHP: {error: $message}. Not a Telegram/VK machine code and not {code,message,data}.

string

Example

{
  "error": "WP2Tutor Ai module is not available."
}