Available entry handlers

This page lists every entry an agent can have. Each entry’s section holds its settings, its shape in a config file, and, for an entry handler, the variables a prompt can read. servflowai resource handler describe --all prints the same catalog. For what entries are and how to choose one, see Entries and entry handlers.

Entry type in the dashboard	`type`	`handlerConfig.type`	Path	Replies to
Trigger — run manually or on a schedule	`trigger`	none	No	Nobody. The reply is logged.
Webhook — a plain HTTP request starts the agent	`handler`	empty	Yes	Whoever sent the request.
GitHub webhook	`handler`	`github_webhook`	Yes	The pull request or issue, when `respond_to` allows.
Gitea webhook	`handler`	`gitea_webhook`	Yes	The pull request or issue, when `respond_to` allows.
Streamable webhook	`handler`	`streamable_http_webhook`	Yes	Whoever opened the Server-Sent Events stream.
Telegram bot	`handler`	`telegram_webhook`	Yes	The chat the message came from.
Discord bot	`handler`	`discord_gateway`	No	The channel the message came from.

The keys every entry shares, type and start, and the rules for an agent with several entries are in the CLI reference.

Entries without a handler

Trigger

Starts the agent on a schedule, by hand from the editor, or when another agent hands it a task.

Key	Dashboard label	Type	Required	Default	Description
`trigger.cron`	Run on a schedule	string	No	empty	A cron expression with six fields, seconds first, such as `0 0 9 * * 1-5` for 09:00 on weekdays. A descriptor such as `@hourly` or `@every 5m` also works. Empty means the agent runs only when it is started.

entries:
  - type: trigger
    trigger:
      cron: "0 0 9 * * 1-5"
    start: agent.digest

Webhook

Answers POST requests on its path. Nothing about the request is checked in advance. Prompts read the request with the body, param, header, and urlparam functions. See the Dynamic content reference.

Key	Dashboard label	Type	Required	Description
`handlerConfig.path`	Path	string	Yes	The path the agent answers on, such as `/ask`.

Response	When
`200`, with the agent’s final reply as `text/plain`	The agent said something.
`204`, with no body	The run finished and the agent said nothing.
`429`	The request continued a conversation that has already started as many runs in the last hour as the agent’s `settings.conversationRunsPerHour` allows.
`500`	The run failed.

Every response carries an X-Conversation-Id header naming the conversation the run used. A request that sends the same header continues that conversation. A request without it starts a new one. When a request is refused with 429, that same header still names the conversation it would have continued. Set the limit on the agent itself:

name: support-bot
settings:
  conversationRunsPerHour: 60
entries:
  - type: handler
    handlerConfig:
      path: /ask
    start: agent.answer

A value of 0 means no limit, which is the default. The limit applies only to runs that continue a conversation, so a test run or any run with no conversation id is not counted.

entries:
  - type: handler
    handlerConfig:
      path: /ask
    start: agent.answer

streamable_http_webhook

Answers POST requests on its path the same way as a webhook entry, but as a stream of Server-Sent Events instead of one response at the end. Use it when your application should receive the agent’s messages as they are written. Prompts read the request with the same body, param, header, and urlparam functions.

Key	Dashboard label	Type	Required	Description
`handlerConfig.path`	Path	string	Yes	The path the agent answers on, such as `/ask-stream`.

Event or response	When
`message`	The agent adds an assistant message. The event data is JSON with `id`, optional `parent_id`, and `text`.
`tool_call`	The agent starts a tool call. The event data is JSON with `id`, optional `parent_id`, and `text`, always `calling tool`. Tool arguments and results are not streamed.
`done`	The run finished. The event data is JSON with `conversation_id` and the final `text`, the same reply a webhook would have returned.
`error`	The run failed after the stream opened. The event data is JSON with `error`.
`429`	The request continued a conversation that has already started as many runs in the last hour as the agent’s `settings.conversationRunsPerHour` allows, or the agent could not start another run right now.
`500`	The run failed before the stream opened.

The stream opens only when the run adds its first message. A refusal before that still comes back as an ordinary HTTP response. Once the stream is open, ServFlow sends keepalive comments so idle proxies do not cut the connection. Like a webhook, the response carries an X-Conversation-Id header naming the conversation the run used. Send the same header on the next request to continue that conversation.

entries:
  - type: handler
    handlerConfig:
      type: streamable_http_webhook
      path: /ask-stream
    start: agent.answer

Entry handlers

An entry handler receives from one outside service and delivers the agent’s reply to it. A prompt reads a handler’s variables as {{ .<namespace>.<key> }}, such as {{ .github.comment_body }}. A handler’s settings are read once, when the agent loads. The only template function they accept is secret.

github_webhook

Runs on a delivery from a GitHub App: an issue or pull request comment, a review comment, a new pull request, a push. When respond_to says so, the agent’s answer is posted on the pull request or issue that started the run. Namespace: github. Needs a path. Integration type: github_app. A delivery is answered 202 at once, and the run continues after the response. Each delivery runs in a conversation of its own. A delivery that the settings filter out, or that comes from an installation other than the integration’s, is answered 202 with {"status":"ignored"} and starts no run. Settings

Key	Dashboard label	Type	Required	Default	Description
`integration`	App	integration	Yes	none	The App whose deliveries this entry answers, and whose identity it replies as. Its webhook secret authenticates every delivery.
`events`	Deliveries, or Set events and actions directly under Advanced settings	string list	No	every event the App is subscribed to	`X-GitHub-Event` names this entry accepts, such as `issue_comment`, `pull_request`, `pull_request_review_comment`, `issues`, `push`.
`actions`	Deliveries, or Set events and actions directly under Advanced settings	string list	No	any action	Delivery actions this entry accepts, such as `opened`, `created`, `synchronize`.
`trigger_text`	Trigger text	string	No	the App’s own handle	What a comment has to say to be talking to this agent. Set it to be summoned by something other than the App’s name, such as `/review`.
`respond_to`	Reply on	string list	No	never replies; the answer only reaches the log	Which kinds of delivery get the agent’s answer posted back. Values: `pull_request` (The pull request thread), `issue` (The issue thread).
`update_pr_comment`	the choice between Rewrites the one it left before and Is posted as a new comment each time	boolean	No	`false`	Edits the comment this agent last left on the pull request instead of posting another one under it.

In a config file

entries:
  - type: handler
    handlerConfig:
      type: github_webhook
      path: /hooks/pull-request
      config:
        integration: my-github-app
        events: [pull_request]
        actions: [opened, synchronize]
        respond_to: [pull_request]
    start: agent.review

Variables

Key	Type	Description
`event`	string	The `X-GitHub-Event` the delivery carried.
`action`	string	The delivery’s action, such as `opened` or `synchronize`.
`delivery`	string	GitHub’s delivery id, for matching a run to a redelivery.
`repo`	string	The repository’s full name, `owner/name`.
`installation_id`	number	The App installation this delivery is for. Always the integration’s installation.
`is_pr`	boolean	Whether the delivery is about a pull request.
`pr_number`	number	The pull request or issue number.
`is_comment`	boolean	Whether the delivery is a comment.
`comment_body`	string	The comment’s text.
`sender_login`	string	Who caused the delivery.
`sender_is_bot`	boolean	Whether the sender is a bot account.
`comment_app_id`	number	The App a comment was written through, when GitHub says.
`app_slug`	string	This App’s slug, as GitHub reports it.
`trigger_text`	string	What a comment had to name to reach this agent.

gitea_webhook

Runs on a delivery from a Gitea server: an issue or pull request comment, a new pull request, a push. Receiving needs only the secret the webhook was created with in Gitea. When respond_to says so, the agent’s answer is posted on the pull request or issue that started the run, which needs an integration. Namespace: gitea. Needs a path. Integration type: gitea, needed only to reply. Settings

Key	Dashboard label	Type	Required	Default	Description
`webhook_secret`	Webhook secret	string	Yes	none	The secret the webhook was created with in Gitea. Every delivery is verified against it. Write it as `{{ secret "name" }}`. The secret has to exist when the agent is saved.
`integration`	Answer as	integration	When `respond_to` is set	no account, so the answer only reaches the log	The server and account an answer is posted as.
`events`	Events	string list	No	every event the webhook sends	`X-Gitea-Event` names this entry accepts, such as `issue_comment`, `pull_request`, `issues`, `push`.
`actions`	Only these actions	string list	No	any action	Delivery actions this entry accepts, such as `opened`, `created`, `synchronized`.
`trigger_text`	Trigger text	string	No	every comment runs the agent	What a comment has to say to be talking to this agent, such as `@reviewbot` or `/review`.
`respond_to`	Post the answer back to	string list	No	never posts; the answer only reaches the log	Which kinds of delivery get the agent’s answer posted back. Values: `pull_request` (Pull requests), `issue` (Issues).
`update_pr_comment`	When a push adds commits, under Advanced settings	boolean	No	`false`	Edits the comment this agent last left on the pull request instead of posting another one under it.

In a config file

entries:
  - type: handler
    handlerConfig:
      type: gitea_webhook
      path: /hooks/gitea
      config:
        webhook_secret: '{{ secret "gitea-webhook-secret" }}'
        integration: my-gitea
        events: [pull_request]
        actions: [opened, synchronized]
        respond_to: [pull_request]
    start: agent.review

Variables

Key	Type	Description
`event`	string	The `X-Gitea-Event` the delivery carried, such as `issue_comment`.
`event_type`	string	The more specific `X-Gitea-Event-Type`, such as `pull_request_comment`.
`action`	string	The delivery’s action, such as `opened` or `synchronized`.
`delivery`	string	Gitea’s delivery id, for matching a run to a redelivery.
`repo`	string	The repository’s full name, `owner/name`.
`is_pr`	boolean	Whether the delivery is about a pull request.
`pr_number`	number	The pull request or issue number.
`is_comment`	boolean	Whether the delivery is a comment.
`comment_id`	number	The comment’s own id.
`comment_body`	string	The comment’s text.
`sender_login`	string	Who caused the delivery.
`trigger_text`	string	What a comment had to name to reach this agent. Empty when any comment does.

telegram_webhook

Runs on a message delivered by the Telegram Bot API, and sends the agent’s answer back to the chat it came from. Each chat keeps one conversation, so the agent remembers earlier messages in that chat. Namespace: telegram. Needs a path. Integration type: telegram_bot. Settings

Key	Dashboard label	Type	Required	Default	Description
`integration`	Bot	integration	Yes	none	The bot this entry receives as and answers as. Its secret token authenticates every delivery.
`chat_types`	Chats	string list	No	all three	The kinds of chat this agent answers in. Values: `private` (Direct messages), `group` (Groups), `supergroup` (Supergroups).
`allowed_chats`	Only these chats	string list	No	any chat	Chat ids or `@usernames` this agent answers. Anything else is ignored.
`require_mention`	Require mention	string	No	no mention required	The text a group message must contain to run the agent, such as `@mybot`. Group chats only.
`commands`	Only these commands	string list	No	every message runs the agent	Slash commands this agent answers, written without the slash, such as `ask` for `/ask`. A message that is not one of them is ignored.
`ignore_bots`	Messages from bots	boolean	No	`false`	Ignores messages sent by other bots.
`typing`	While the agent works	boolean	No	`true`	Shows “typing…” in the chat for the length of the run.
`reply_in_thread`	Attach the answer to the question	boolean	No	on in groups, off in private chats	Quotes the message that asked, instead of answering the chat.
`parse_mode`	Formatting, under Advanced settings	string	No	plain text	How Telegram renders the answer. Values: `MarkdownV2`, `HTML`. Leave it unset unless the agent is told to write that markup. One unescaped character costs the whole message.

In a config file

entries:
  - type: handler
    handlerConfig:
      type: telegram_webhook
      path: /hooks/telegram
      config:
        integration: my-telegram-bot
        chat_types: [private, group]
        require_mention: "@mybot"
        commands: [ask]
    start: agent.answer

Variables

Key	Type	Description
`text`	string	The message text.
`chat_id`	number	The chat the message arrived in.
`chat_type`	string	`private`, `group`, or `supergroup`.
`chat_title`	string	The group’s title. Empty in a private chat.
`chat_username`	string	The chat’s `@username`, when it has one.
`message_id`	number	The message’s id.
`update_id`	number	Telegram’s update id.
`user_id`	number	Who sent the message.
`username`	string	The sender’s `@username`.
`first_name`	string	The sender’s first name.
`is_bot`	boolean	Whether the sender is a bot.
`is_command`	boolean	Whether the message starts with a `/command`.
`command`	string	The command name, without the slash.
`args`	string	Everything after the command.
`reply_to_text`	string	The text of the message this one replies to.
`thread_id`	number	The forum topic this message belongs to. `0` outside one.

discord_gateway

Connects to Discord as a bot and runs on the messages it hears, answering in the channel that asked. It connects out to Discord, so it has no path and needs no address Discord can reach. The bot needs the Message Content intent turned on in the Discord developer portal. Each channel keeps one conversation, and a Discord thread counts as a channel of its own. Namespace: discord. No path. Integration type: discord. Settings

Key	Dashboard label	Type	Required	Default	Description
`integration`	Bot	integration	Yes	none	The bot this entry connects and answers as.
`super_user`	Super user	string	No	none	The Discord user this agent treats as its operator, as a user id or an `@username`. Sets `is_super_user` on each run. An id is the safer of the two, because a username can change hands.
`chat_types`	Places	string list	No	all three	Where a message may arrive from. Values: `guild` (Server channels), `dm` (Direct messages), `thread` (Threads).
`require_mention`	Require mention	boolean	No	`false`	Runs only when the message mentions the bot.
`typing`	While the agent works	boolean	No	`true`	Shows the typing indicator in the channel for the length of the run.
`allowed_guilds`	Only these servers, under Advanced settings	string list	No	any server	Server ids this agent answers in.
`allowed_channels`	Only these channels, under Advanced settings	string list	No	any channel	Channel ids this agent answers in.
`ignore_bots`	Messages from bots, under Advanced settings	boolean	No	`true`	Ignores messages sent by other bots.
`commands`	Only these ! commands, under Advanced settings	string list	No	every message runs the agent	Commands this agent answers, written without the `!` a message carries.

In a config file

entries:
  - type: handler
    handlerConfig:
      type: discord_gateway
      config:
        integration: my-discord-bot
        chat_types: [guild, thread]
        require_mention: true
        super_user: "905712398471923849"
    start: agent.answer

Variables

Key	Type	Description
`content`	string	The message text, with the bot’s own mention removed.
`channel_id`	string	The channel the message arrived in.
`parent_channel_id`	string	The channel a thread hangs under. Empty outside a thread.
`guild_id`	string	The server. Empty in a direct message.
`chat_type`	string	`guild`, `dm`, or `thread`.
`message_id`	string	The message’s id.
`author_id`	string	Who sent the message.
`username`	string	The sender’s username.
`display_name`	string	The sender’s nickname in this server, or their username.
`is_bot`	boolean	Whether the sender is a bot.
`is_super_user`	boolean	Whether the sender is the configured super user.
`mentions_me`	boolean	Whether the message mentions the bot.
`is_command`	boolean	Whether the message starts with a `!command`.
`command`	string	The command name, without the `!`.
`args`	string	Everything after the command.
`reply_to_text`	string	The text of the message this one replies to.
`reply_to_author`	string	Who wrote the message this one replies to.
`message_link`	string	A link to the message.

Entries and entry handlers

What entries are, and how to choose one.

Available integrations

The integration each handler needs.

CLI reference

The keys every entry shares, and the rules for several entries.

Dynamic content reference

The functions a webhook entry reads the request with.

Getting started

Guides

Concepts

References

Entries without a handler

Trigger

Webhook

streamable_http_webhook

Entry handlers

github_webhook

gitea_webhook

telegram_webhook

discord_gateway

Entries and entry handlers

Available integrations

CLI reference

Dynamic content reference

​Entries without a handler

​Trigger

​Webhook

​streamable_http_webhook

​Entry handlers

​github_webhook

​gitea_webhook

​telegram_webhook

​discord_gateway

​Related

Entries and entry handlers

Available integrations

CLI reference

Dynamic content reference

Entries without a handler

Trigger

Webhook

streamable_http_webhook

Entry handlers

github_webhook

gitea_webhook

telegram_webhook

discord_gateway

Related