Triggers

A trigger binds an inbound event on a channel integration to a published agent. The agent’s config never names the channel, so repointing a trigger changes which agent answers on the next message, with no republish.

`trigger_type`	Integration	Agent channel
`telegram.message.inbound`	Telegram	`text`
`whatsapp.message.inbound`	WhatsApp (Twilio or Gupshup)	`text`
`whatsapp.call.inbound`	WhatsApp, Twilio numbers only	`voice`

Walkthroughs: Telegram, WhatsApp, WhatsApp calls.

Creating one

INTEGRATION_ID=7c2f1a90-4e83-4d16-9b7a-2c5e08f31d64

curl -X POST "https://api.talqing.com/v1/integrations/$INTEGRATION_ID/triggers" \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_type": "telegram.message.inbound",
    "agent_id": "9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704",
    "enabled": true
  }'

const trigger = await talqing.integrations.triggers.create({
  integration_id: "7c2f1a90-4e83-4d16-9b7a-2c5e08f31d64",
  createIntegrationTriggerRequest: {
    trigger_type: "telegram.message.inbound",
    agent_id: "9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704",
    enabled: true,
  },
});
console.log(trigger.status); // "active"

trigger = talqing.integrations.triggers.create(
    "7c2f1a90-4e83-4d16-9b7a-2c5e08f31d64",
    trigger_type="telegram.message.inbound",
    agent_id="9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704",
    enabled=True,
)
print(trigger["status"])  # "active"

string

required

One of the three types above.

uuid

The agent that answers. Required to enable; without it the trigger is needs_setup.

boolean

default:"false"

Turning it on runs the checks below and registers the webhook with the provider.

string

default:"public_reply"

public_reply or none. See reply modes.

object

Yours, returned untouched.

provider_subscription_ref on the response is written by the platform when the webhook is registered (for Telegram, the callback URL).

What enabling checks

These run on create with enabled: true and on any PATCH that leaves the trigger enabled, including repointing agent_id.

Requirement	Refusal
The integration is `active`	`400` `activate or reconnect this integration before enabling a trigger`
The provider supports the type	`400` `integration provider <provider> does not support trigger <type>`
`whatsapp.call.inbound` is on a Twilio number	`400` `WhatsApp calls work only on numbers connected through Twilio`
An agent is named	`400` `select an agent before enabling this trigger`
The agent exists	`404` `agent not found`
The agent is published	`400` `publish the agent before enabling this trigger`
The published version is on the right channel	`400` `<type> requires a published <channel> agent`
`whatsapp.call.inbound`: every required `vars` entry has a default	`400` — a WhatsApp call carries no request to supply it
No other enabled trigger of this type on this integration	`400` `this integration already has an enabled trigger of that type`

The channel check reads the published version; editing the draft changes nothing until you publish. While an enabled trigger points at an agent, deleting the agent is refused with 409 naming the integration, and publishing it on a different channel is refused.

Enabling registers the webhook

Enabling registers the callback URL with the provider for you; nothing is pasted into BotFather or a BSP console. If the provider refuses, the trigger is saved with enabled: false and status: "error", and the call returns the provider’s message (for Telegram, 502 Telegram webhook registration failed: …). Fix the cause and PATCH {"enabled": true} again. Disabling or deleting a trigger unregisters it. Disabling the integration unregisters all its enabled triggers and enabling it registers them again. Messages sent while a trigger is off are never answered.

Statuses

status is recomputed on every write. The only value you can set yourself is error.

`status`	Meaning
`active`	Enabled and registered. The only status that answers
`disabled`	Off; everything else checks out
`needs_setup`	Off, and no agent is named or the agent was never published
`error`	Registration with the provider failed, or you set it

Reply modes

`reply_mode`	Effect
`public_reply`	The reply is sent to the person. Default
`none`	The agent runs and the reply is stored on the conversation (`delivery_status: "skipped"`) but not sent. Use it to shadow a channel with a new agent

The API also accepts internal_note, but no current provider supports it: the reply is never sent and the item settles skipped with provider <provider> does not support reply_mode:internal_note. Do not use it.

Changing and removing

PATCH /v1/integrations/{integration_id}/triggers/{trigger_id} — same fields; omitted fields are kept.
DELETE /v1/integrations/{integration_id}/triggers/{trigger_id} — permanent; unregisters the webhook.
GET /v1/integrations/{integration_id}/triggers — list.

curl -X PATCH "https://api.talqing.com/v1/integrations/$INTEGRATION_ID/triggers/$TRIGGER_ID" \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "1b7d4c60-9e35-4a12-b8f3-6c0e5d29a417"}'

What a fired trigger produces

A message trigger starts a chat when the person has no open one; later messages join it until it ends. A call trigger starts a call. Either is a session on that person’s conversation, read back like any other (conversations).

Deploy a text agent to a Telegram bot.

Put a text agent on a WhatsApp number.

Get started

Build

Guides

Creating one

What enabling checks

Enabling registers the webhook

Statuses

Reply modes

Changing and removing

What a fired trigger produces

Next

Telegram

WhatsApp

​Creating one

​What enabling checks

​Enabling registers the webhook

​Statuses

​Reply modes

​Changing and removing

​What a fired trigger produces

​Next

Telegram

WhatsApp

Creating one

What enabling checks

Enabling registers the webhook

Statuses

Reply modes

Changing and removing

What a fired trigger produces

Next