@talqing/mcp 0.11.0 → 0.12.0

package/SKILL.md

@@ -37,8 +37,10 @@ An agent is a single object, `config`, plus what you attach to it:
 - **`prompt`** — the system prompt. This is where the agent's behaviour lives.
 - **`greeting`** — the line spoken on connect, and on the way in from a
   handoff. Voice and video only. `greeting_interruptible: false` makes the
-  caller unable to cut it off (cascade only); a greeting speaking the recording
-  notice is always protected.
+  caller unable to cut it off (cascade only). To tell callers they are recorded,
+  set `recording.notice` to the sentence and put `{{recording.notice}}` in the
+  greeting where it should be spoken; it plays uninterruptibly, needs recording
+  on and a cascade pipeline, and `null` means no notice.
 
   Both are personalized per session: `{{userdata.field}}` is substituted from
   the session's userdata when the agent starts, so *"You are speaking with
@@ -55,22 +57,28 @@ An agent is a single object, `config`, plus what you attach to it:
   Two more roots are filled in from outside the session, and nothing inside one
   can write either. They differ in who fills them.
 
-  **`{{system_vars.…}}` — ours.** Six keys, and any other is rejected at save;
-  `GET /v1/catalog` returns them as `system_vars`.
-
-  - `{{system_vars.human_phone_number}}` — the other party, the caller inbound
-    and the person you called outbound
-  - `{{system_vars.agent_phone_number}}` — your number on this call
-  - `{{system_vars.direction}}` — `inbound` or `outbound`
+  **`{{system_vars.…}}` — ours.** Seven keys, and any other is rejected at save;
+  `GET /v1/catalog` returns them as `system_vars`, each with the `channels` it
+  has a value on.
+
+  - `{{system_vars.human_phone_number}}` — the person's number: who called or
+    wrote to you, or whom you called or wrote to
+  - `{{system_vars.agent_phone_number}}` — your number in this session
+  - `{{system_vars.direction}}` — `inbound` when they started the call or chat,
+    `outbound` when you did
+  - `{{system_vars.channel}}` — where the session is happening: `phone_call`,
+    `whatsapp_call`, `whatsapp_message`, `web_call`, `chat`, `telegram` or `stream`
   - `{{system_vars.now}}` — `2026-08-19T19:26:59+05:30`, the machine format;
     send it to an API, never read it aloud
   - `{{system_vars.date}}` — `Wednesday, 19 August 2026`
   - `{{system_vars.time}}` — `7:26 PM`
 
-  The first three come from the call, so they are empty on web calls and on text
-  conversations — do not make one the only source of a fact the agent needs. One
+  The first three come from a phone number — phone calls, WhatsApp calls,
+  WhatsApp chats and media streams — so they are empty on web calls, API chats
+  and Telegram; do not make one the only source of a fact the agent needs. One
   agent can greet a caller and someone it called differently by branching on
-  `{{system_vars.direction}}`. The last three come from the agent's
+  `{{system_vars.direction}}`, and one agent on several channels can adapt by
+  branching on `{{system_vars.channel}}`. The last three come from the agent's
   **`timezone`** and work on every channel; using one without setting `timezone`
   is a save error. In a prompt or greeting the clock is frozen at the moment the
   agent started (re-resolving would throw away the model's prompt cache); inside
@@ -107,8 +115,9 @@ An agent is a single object, `config`, plus what you attach to it:
   Four things to get right:
 
   - **They are visible to the model.** Anything in `vars` may be read aloud or
-    repeated back. A credential belongs in a workspace secret, read as
-    `{{secrets.NAME}}` from a tool, where the model never sees it.
+    repeated back. A credential belongs in `secrets` on the same request when it
+    is per session, or in a workspace secret when it is shared — either is read
+    as `{{secrets.NAME}}` from a tool, where the model never sees it.
   - **`required: true` refuses the session** that supplies no value for a
     variable with no `default` — the call token, the dial, the batch and the chat,
     before anything is compiled and before any provider is called.
@@ -649,17 +658,21 @@ states what to add; do not try to turn the derived silence off.
 this tool run's own state, `{{userdata.field}}` the session's state,
 `{{system_vars.field}}` what the platform knows about this session,
 `{{vars.field}}` what the tenant supplied for it, and `{{secrets.NAME}}` a
-workspace secret. A string that is exactly one template token keeps the resolved
-value's type. Every one of these works in a URL, in the query, in the body **and
-in headers**. A token whose root is not one of those six is an error at save,
-not text.
-
-`system_vars` is read-only, and its six keys are the same ones the agent's prompt
-reads: `human_phone_number`, `agent_phone_number`, `direction`, `now`, `date`,
-`time`. So a tool can POST the caller's number to a CRM, stamp a record with
-`{{system_vars.now}}`, or branch an `if` on the direction without the agent
-having to ask. The phone-call keys are empty on web calls, on text conversations
-and in a dashboard test run; the clock keys resolve wherever the agent has a
+secret — the session's own if it brought one of that name, else the workspace's.
+A string that is exactly one template token keeps the resolved value's type.
+Every one of these works in a URL, in the query, in the body **and in headers**.
+A token whose root is not one of those six is an error at save, not text.
+**A secret may only be sent by an `http` operation or read by a `code`
+operation**: `{{secrets.…}}` in any other operation (`say`, `set_variable`,
+`if`, `frontend_rpc`, `generate_reply`, a handoff…) is refused at save, because
+it would be spoken, shown or stored.
+
+`system_vars` is read-only, and its seven keys are the same ones the agent's prompt
+reads: `human_phone_number`, `agent_phone_number`, `direction`, `channel`, `now`,
+`date`, `time`. So a tool can POST the person's number to a CRM, stamp a record
+with `{{system_vars.now}}`, or branch an `if` on the direction or the channel
+without the agent having to ask. The phone keys are empty on web calls, API chats,
+Telegram and in a dashboard test run; the clock keys resolve wherever the agent has a
 `timezone`, and read the time the **tool ran** rather than the time the call
 started.
 
@@ -916,7 +929,7 @@ message, draft an opening line, take a shipping address mid-call.
   reads `{{vars.name}}` for the values the run was given, and
   `{{system_vars.now}}` / `.date` / `.time` when `timezone` is set. It does
   **not** read `{{system_vars.human_phone_number}}` / `.agent_phone_number` /
-  `.direction` — there is no call.
+  `.direction` / `.channel` — there is no session.
 - **`llm`** — one model, with the same `fallback`, `reasoning_effort`,
   `priority` and `builtin_tools` an agent's LLM has. A provider tool runs inside
   a step rather than as one, so it costs no steps and real seconds. It is the
@@ -1054,10 +1067,11 @@ rest — it never refuses for load. `run_task_batch` queues up to 1000 runs of o
 call, all or nothing: one invalid item refuses the batch, naming `runs[i]`. Give
 each run `metadata` (≤16 string labels, e.g. `{candidate_id: "c_42"}`) and an
 `idempotency_key`: resending a key returns the existing run (`deduplicated`)
-instead of starting another, and the same key with a different request is a
-`409`. Read results with `list_task_runs` (filter by `task_id`, `status`,
-`metadata=key:value`, a creation window) and `get_task_run`, or subscribe a
-webhook to `task_run.completed`, sent once per run as it finishes.
+instead of starting another — even after the task was republished — and the same
+key with a different request is a `409`. Read results with `list_task_runs`
+(filter by `task_id`, `status`, `metadata=key:value`, a creation window) and
+`get_task_run`, or subscribe a webhook to `task_run.completed`, sent once per run
+as it finishes.
 
 **Retries.** A background run is tried again — at most 3 tries — when its
 worker stopped under it, or when the model provider failed transiently before
@@ -1450,11 +1464,47 @@ Replies are answered by the agent on the sender's
 `{{userdata.<column>}}` and the whole template, buttons included, as its own
 first message — so write that agent's prompt against the CSV's column names.
 
+A tapped quick-reply button reaches the agent as its text; the item's `content`
+keeps the button's `payload` (never shown to the agent) and `replied_to`, the
+template it answers. Photos reach an agent whose model has `vision: true`; any
+other agent is told to ask for a description, so pick a vision model for a
+number people send photos to. Voice notes, video and documents are not read.
+
+**One message to one person** is `create_conversation_item`, not a batch. `to`
+is a `conversation_id`, or `number` (your WhatsApp sender, E.164) plus `peer`
+(their number) to reach someone with no conversation yet. Four `type`s:
+
+- `template` — an approved template with every variable filled
+  (`template.variables`); may go any time.
+- `agent_text` — free text sent as the agent's own message.
+- `note` — background for the agent, never delivered (any contact, PSTN ones too).
+- `instruct` — the agent writes and sends the next message itself, in the
+  conversation's language, without ever saying it was instructed. Refused with
+  `voice_session_live` while they are on a call with the agent.
+
+WhatsApp allows free text only within **24 hours of their last message or
+call** (`ref.whatsapp_window_expires_at`). Outside it `agent_text` and
+`instruct` are refused with `whatsapp_window_closed`, unless
+`on_window_closed: {opener: {id, variables}}` names a template to send first:
+the text is then `held` until they reply, and `expired` after 7 days. Prefer an
+opener over a bare template when what you want to say is free-form.
+`userdata` on a post joins the contact's and is what the agent answering their
+reply starts from. Send an `idempotency_key` when retrying is possible. A
+provider refusal still stores the item, `delivery_status: failed` (nothing resends it). While
+they have an open chat, post anything but a note into that chat's conversation:
+another one is refused with `chat_open_elsewhere`.
+
 ## Secrets, keys and webhooks
 
 **Secrets** are workspace values referenced as `{{secrets.NAME}}` from tool
 operations and integration config. They are write-only: once stored, only the
-runtime resolves them.
+runtime resolves them. A session can also bring its own, as `secrets` on the
+request that starts it; for that session they join the workspace's under the
+same `{{secrets.NAME}}`, the session's value winning. A tool that reads a name
+that is not a workspace secret saves with a warning, and starting a session
+without supplying it is refused — an inbound call or chat, which has no
+request, gets one only from the inbound webhook below. Integration and carrier
+credentials and MCP server headers must be workspace secrets.
 
 **BYOK.** Talqing runs agents on the workspace's own provider API keys and has
 none of its own. `list_provider_keys` says which providers are configured, and
@@ -1465,7 +1515,21 @@ there, tell them the key has to be added before the agent can publish.
 
 **Webhooks** are workspace-wide and fire for every agent. `event_types` lists
 what can be subscribed to, and `webhook_deliveries` is where to look when one
-seems silent.
+seems silent. `session.refused` fires for every inbound call or channel chat
+turned away before an agent ran.
+
+**The inbound webhook** is how an inbound PSTN call, WhatsApp call or new
+WhatsApp/Telegram chat gets what an outbound request would carry. An agent with
+`inbound_webhook: true` has Talqing POST `session.request` (channel, numbers,
+`contact_key`, the opening message) to the workspace's one URL
+(`set_inbound_webhook`) before the session starts; the answer may set `vars`,
+`secrets`, `agent_override`, `metadata` and `userdata`, each meaning what it
+means on `create_outbound_call`. No valid answer within 3 s **refuses the
+session** (`inbound_webhook_failed`, reason in `error`), so publishing such an
+agent needs the webhook set, and `test_inbound_webhook` checks a reply before
+real callers depend on it. A chat asks once, when it opens. `metadata` — the
+caller's own labels — appears on the call or chat and filters `list_calls` and
+`list_chats` (`metadata=key:value`).
 
 ## Running an agent, and reading what happened
 
@@ -1488,9 +1552,14 @@ every agent the session runs and is gone when the session ends. Use `userdata`
 for facts about the person and `vars` for configuration of the session; unlike
 `userdata`, `vars` is never written onto the caller's contact record and no tool
 can change it mid-session. An empty string is a deliberate blank, not a request
-for the default. The model can see the values, so credentials stay in workspace
-secrets. On a batch it is one bag for the whole campaign, copied onto every call
-it places — per-person data is what a recipient's `userdata` is for.
+for the default. The model can see the values, so credentials go in secrets. On
+a batch it is one bag for the whole campaign, copied onto every call it places —
+per-person data is what a recipient's `userdata` is for.
+
+All three (not batches) also take `secrets`, `{NAME: value}`: credentials for
+that one session, read by its tools as `{{secrets.NAME}}` and never shown to the
+model or returned. A web call's `resume_call` keeps them, and its own `secrets`
+adds or replaces.
 
 **Per-call configuration.** All three — and `create_call_batch` — also take four
 fields that change what runs on that one call:
@@ -1537,7 +1606,13 @@ rather than as two messages. The agent's model must have `vision` (see *Images*
 above) or the call is refused naming the model.
 
 **Reading it back.** A *conversation* is the thread with a person, on any
-surface; a *call* is one voice or video session. `list_conversations` and
+surface; a *call* is one voice or video session. A person is one **contact**
+(`contact_key`) per business number: `phone:<your number>:<their number>` spans
+phone calls, WhatsApp messages and WhatsApp calls on that number, with one
+`userdata`. Which thread a session writes to is the answering agent's
+`conversation.context` (`transcript` joins their newest thread), except that a
+WhatsApp call always joins their open WhatsApp chat. Every item carries the
+`channel` it arrived on. `list_conversations` and
 `list_conversation_items` are the transcript; `list_conversation_sessions` lists
 its calls and chats, and `get_chat` gives one chat's cost and analysis.
 `list_calls` and `get_call` cover phone and web calls — `get_call` gives the transcript with every tool call and
@@ -1549,6 +1624,13 @@ What a run costs is the provider spend on the workspace's own keys plus
 Talqing's platform fee, which `get_catalog` gives: per minute on voice and
 video, and $0.0001 per answered message on text.
 
+Items posted through `create_conversation_item` carry `post_type` and the
+`author` you gave (shown to people, never to the agent or the contact). Notes and
+instructions have no `channel`. Outbound WhatsApp and Telegram messages move
+through `delivery_status` (`queued`, `sent`, `delivered`, `read`, or
+`undelivered`/`failed` with `delivery_error`), and each move fires the
+`conversation.item.status` webhook.
+
 When an agent misbehaves, read the actual run before theorizing. The transcript
 and the final `userdata` usually name the cause.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talqing/mcp",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "MCP server for building Talqing AI voice, video and text agents from Claude Code, Codex, or any MCP client.",
   "license": "MIT",
   "homepage": "https://talqing.com",

package/tools.json

@@ -1934,6 +1934,20 @@
       "read_only": false,
       "role": "write"
     },
+    {
+      "description": "Post a template, agent text, note or instruction into a conversation, or start one with a person.",
+      "method": "POST",
+      "name": "create_conversation_item",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('create_conversation_item').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/conversations/items",
+      "read_only": false,
+      "role": "write"
+    },
     {
       "description": "Workspace analytics: volume, endings, recordings, response time and spend. One snapshot of a date range, up to 7 days.",
       "method": "GET",
@@ -2102,6 +2116,76 @@
       "read_only": true,
       "role": "read"
     },
+    {
+      "description": "Get the workspace's inbound session webhook.",
+      "method": "GET",
+      "name": "get_inbound_webhook",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('get_inbound_webhook').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/inbound-webhook",
+      "read_only": true,
+      "role": "read"
+    },
+    {
+      "description": "Set the URL asked for an inbound session's configuration.",
+      "method": "PUT",
+      "name": "set_inbound_webhook",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('set_inbound_webhook').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/inbound-webhook",
+      "read_only": false,
+      "role": "write"
+    },
+    {
+      "description": "Remove the inbound session webhook.",
+      "method": "DELETE",
+      "name": "delete_inbound_webhook",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('delete_inbound_webhook').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/inbound-webhook",
+      "read_only": false,
+      "role": "write"
+    },
+    {
+      "description": "Issue a new signing secret; the old one stops working at once.",
+      "method": "POST",
+      "name": "rotate_inbound_webhook_secret",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('rotate_inbound_webhook_secret').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/inbound-webhook/rotate-secret",
+      "read_only": false,
+      "role": "write"
+    },
+    {
+      "description": "Send a sample request and check the reply against the response schema.",
+      "method": "POST",
+      "name": "test_inbound_webhook",
+      "parameters": {
+        "additionalProperties": true,
+        "description": "Arguments not inlined: call describe_function('test_inbound_webhook').",
+        "properties": {},
+        "type": "object"
+      },
+      "path": "/v1/inbound-webhook/test",
+      "read_only": false,
+      "role": "write"
+    },
     {
       "description": "The provider catalog: every LLM, STT, TTS, realtime and avatar model that agents may use.",
       "method": "GET",