Build on Venom Support
Read and triage the support inbox from code or an agent. Assign and tag conversations, add internal notes, draft replies from your notes and send them once a person approves, over REST or MCP.
Venom Support is the organisation's shared inbox: email, Forms responses, the chat widget and messaging channels in one
list of conversations. The inbox, the conversation page, saved replies, SLA policies and the report are MCP tools on
/workspace/mcp/support and REST routes under /api/v1/support.
What you can build
- Triage on arrival. Subscribe to
support.conversation.created, read the conversation (GET /api/v1/support/conversations/{conversation}), then set priority and tags (PATCH) and assign it to a member or team (POST …/assign). - Draft-then-approve replies. Have an agent write a reply from your notes with citations (
support_draft_create), and send it withsupport_reply_send(use_draft: true) only after a person approved the text. - Watch automatic replies. When the org turned on automatic replies, list the drafts waiting to send and today's count (
support_autoreply_get,GET /api/v1/support/auto-reply), and hold one or change its text before it goes (support_draft_update,PATCH /api/v1/support/conversations/{conversation}/draft). Turning automatic replies on is a person's decision in the console; there is no tool for it. - Bug escalation. Turn a conversation into a Venom Tasks issue with the thread summary and a link back (
POST /api/v1/support/conversations/{conversation}/issue). Or add it to an existing issue as a customer request (POST /api/v1/support/conversations/{conversation}/requests, see customer requests). - Breach alerts in your own tools. Subscribe to
support.sla.breachedand page someone, or read response and resolution times withGET /api/v1/support/report. - Saved replies kept in a repo. Sync your macros with
support_macro_create,support_macro_updateandsupport_macro_delete.
At a glance
Generated from the code on every docs build.
| MCP endpoint | https://cloud.usevenom.dev/workspace/mcp/support, server name venom-support |
| Connect | claude mcp add --transport http venom-support https://cloud.usevenom.dev/workspace/mcp/support |
| MCP tools | 26 (9 read, 17 write) |
| OAuth scopes | support:read support:write |
| REST twin | 27 routes under https://cloud.usevenom.dev/api/v1 |
| Webhook events | support.conversation.created, support.sla.breached |
Authentication and scopes
The inbox belongs to the organisation, not to one member, so a team key works as well as a member's key:
- A personal API key acts with its member's role: owner, admin and developer read and write; billing and viewer read. A key marked read-only reads only.
- A team key reads and writes (unless it is read-only). Its notes and replies carry the key's name.
- An OAuth app needs
support:readto use the tools andsupport:writeto change anything, on top of the member's role. - A service agent that an admin scoped to some apps reaches Support only when Support is one of them.
The settings tools, support_sla_policy_save, support_sla_policy_delete and support_widget_save (and their REST
routes), need an owner's or admin's personal key, or an OAuth app with support:write connected by an owner or admin.
A team key, a read-only key and every other role are refused with "Only an owner or admin may change …". The inbound
secret, the outbound provider and its key are set only in the browser.
A conversation assigned to a private org team is visible only to that team's members and the org's owners and admins. A team key is in no team, so it does not see those conversations.
There is no add-on gate on Support's tools. support_draft_create counts against the org's daily AI cap.
A refused change answers 403 over REST, or a tool error that names support:write over MCP. The agent's name is on
every note and reply it writes.
Worked example
Pick up the oldest unassigned urgent conversation, assign it, and have a draft ready for a person to check:
curl "$VENOM_CLOUD/api/v1/support/conversations?view=unassigned&priority=urgent&limit=5" \
-H "Authorization: Bearer $VENOM_API_KEY"
curl -X POST "$VENOM_CLOUD/api/v1/support/conversations/42/assign" \
-H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
-d '{"assignee": "ana@example.com"}'
curl -X POST "$VENOM_CLOUD/api/v1/support/conversations/42/draft" \
-H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' -d '{}'Once Ana approves the draft, send it and close the conversation:
curl -X POST "$VENOM_CLOUD/api/v1/support/conversations/42/reply" \
-H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
-d '{"use_draft": true, "close": true}'The draft over MCP, from any client connected to /workspace/mcp/support:
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": { "name": "support_draft_create",
"arguments": { "conversation": "42", "format": "json" } } }{conversation} is the conversation's id or its number (42, or #42 in a tool argument). macro on the draft starts
it from a saved reply.
Sending replies
support_reply_send sends by email through the org's connected provider, with the thread's subject and headers, or,
on a messaging conversation (WhatsApp, SMS, RCS, Telegram), through Venom Comms on the channel the customer wrote on.
Give body, or use_draft: true for the pending draft; close: true closes the conversation after.
- When a reply cannot go out (no provider connected, no customer address, the provider refused), it is saved on the
thread as not sent and the answer says so:
sent: falsein JSON, with the delivery error. - WhatsApp takes free text only within 24 hours of the customer's last message. After that, the MCP tool takes
template,template_languageandtemplate_paramsfor an approved template; otherwise the reply goes by SMS when the org's support profile allows it, or is refused. The template arguments are not on the REST route. - The tool descriptions tell an agent to draft first and send only after a person approved the text. The server does not enforce that: your integration should.
Inbox views and filters
support_conversation_list (GET /api/v1/support/conversations) takes view: all (open, the default), mine,
teams, unassigned, snoozed or closed, and filters query, tag, priority (low, normal, high,
urgent), assignee and team (an email, id or key, or none), customer, with limit (default 25, at most 100)
and offset. support_conversation_get returns the customer, every message with its delivery state, the pending
draft with citations, the linked Tasks issue, the customer's recent Incidents errors and the CSAT rating.
support_conversation_update changes the subject, priority, tags (tags, add_tags, remove_tags), the customer's
name and company, the linked issue, or reopens it. Over MCP it also takes customer_user_id, the customer's id in
your own product (it matches Incidents error events); that argument is not on the REST route.
support_report_get covers at most a year and the first 20,000 conversations of the range.
Events
2 org webhook events, generated from lib/webhooks/events.ts. Subscribe an endpoint to them in Settings, Webhooks (see Webhooks and events).
| Event | When |
|---|---|
support.conversation.created |
A conversation was opened in Venom Support (email, a form, a messaging channel or by hand): its id, number, subject, channel and priority. Never the customer's message. |
support.sla.breached |
An open Support conversation ran past its first-reply or resolution time: its id, number, which SLA (first_response or resolution), the due time and the priority. Never the customer's message. |
Neither event carries the customer's message: read it with support_conversation_get. Mail comes in through the
org's inbound address, a webhook your mail provider calls with the inbound secret; see
Mail in.
REST routes
The REST twin: 27 routes under https://cloud.usevenom.dev/api/v1, each calling the MCP tool named in its row with the same arguments (see the REST twin).
/support/conversations
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/support/conversations |
The support inbox: conversations by view | support_conversation_list |
| POST | /api/v1/support/conversations |
Open a conversation by hand | support_conversation_create |
| GET | /api/v1/support/conversations/{conversation} |
Read a conversation with its messages and pending draft | support_conversation_get |
| PATCH | /api/v1/support/conversations/{conversation} |
Change a conversation's subject, priority, tags or customer | support_conversation_update |
| POST | /api/v1/support/conversations/{conversation}/close |
Close a conversation | support_conversation_close |
| POST | /api/v1/support/conversations/{conversation}/snooze |
Snooze a conversation until a time | support_conversation_snooze |
| POST | /api/v1/support/conversations/{conversation}/assign |
Assign a conversation to a member and/or a team, or none | support_conversation_assign |
| GET | /api/v1/support/conversations/{conversation}/messages |
A conversation's messages | support_message_list |
| POST | /api/v1/support/conversations/{conversation}/messages |
Add an internal note | support_message_create |
| POST | /api/v1/support/conversations/{conversation}/draft |
Draft a reply with AI from the org's notes (not sent) | support_draft_create |
| PATCH | /api/v1/support/conversations/{conversation}/draft |
Change the pending draft's text, or hold an automatic reply | support_draft_update |
| POST | /api/v1/support/conversations/{conversation}/reply |
Send a reply through the org's email provider | support_reply_send |
| POST | /api/v1/support/conversations/{conversation}/issue |
Create a Tasks issue from a conversation and link it | support_issue_create |
| POST | /api/v1/support/conversations/{conversation}/requests |
Add a conversation to a Tasks issue as a customer request | support_issue_link |
/support/auto-reply
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/support/auto-reply |
The automatic-reply settings, today's count and the drafts waiting to send | support_autoreply_get |
/support/sla-policies
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/support/sla-policies |
SLA policies in the order they are tried | support_sla_policy_list |
| POST | /api/v1/support/sla-policies |
Create an SLA policy | support_sla_policy_save |
| PATCH | /api/v1/support/sla-policies/{policy} |
Change an SLA policy | support_sla_policy_save |
| DELETE | /api/v1/support/sla-policies/{policy} |
Delete an SLA policy | support_sla_policy_delete |
/support/report
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/support/report |
First-response and resolution times, breach rate, volume, agent load and ratings for a date range | support_report_get |
/support/widget
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/support/widget |
The chat widget and help center settings and the embed snippet | support_widget_get |
| PATCH | /api/v1/support/widget |
Change the chat widget and help center | support_widget_save |
/support/help-articles
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/support/help-articles |
The Notes pages the help center shows | support_help_article_list |
/support/macros
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/support/macros |
Saved replies | support_macro_list |
| POST | /api/v1/support/macros |
Save a reply | support_macro_create |
| PATCH | /api/v1/support/macros/{macro} |
Change a saved reply | support_macro_update |
| DELETE | /api/v1/support/macros/{macro} |
Delete a saved reply | support_macro_delete |
MCP tools
26 tools: 9 read, 17 write. Generated from the code; "write (destructive)" is the tool's destructiveHint. A tool with a REST route is the same call over HTTP.
| Tool | Title | Access | Scope | REST route |
|---|---|---|---|---|
support_autoreply_get |
Read the automatic-reply settings | read | support:read |
GET /api/v1/support/auto-reply |
support_conversation_assign |
Assign a support conversation | write | support:write |
POST /api/v1/support/conversations/{conversation}/assign |
support_conversation_close |
Close a support conversation | write | support:write |
POST /api/v1/support/conversations/{conversation}/close |
support_conversation_create |
Open a support conversation | write | support:write |
POST /api/v1/support/conversations |
support_conversation_get |
Read a support conversation | read | support:read |
GET /api/v1/support/conversations/{conversation} |
support_conversation_list |
List support conversations | read | support:read |
GET /api/v1/support/conversations |
support_conversation_snooze |
Snooze a support conversation | write | support:write |
POST /api/v1/support/conversations/{conversation}/snooze |
support_conversation_update |
Change a support conversation | write | support:write |
PATCH /api/v1/support/conversations/{conversation} |
support_draft_create |
Draft a reply with AI | write | support:write |
POST /api/v1/support/conversations/{conversation}/draft |
support_draft_update |
Change or hold the pending draft | write | support:write |
PATCH /api/v1/support/conversations/{conversation}/draft |
support_help_article_list |
List help center articles | read | support:read |
GET /api/v1/support/help-articles |
support_issue_create |
Create a Tasks issue from a conversation | write | support:write |
POST /api/v1/support/conversations/{conversation}/issue |
support_issue_link |
Add a conversation to a Tasks issue | write | support:write |
POST /api/v1/support/conversations/{conversation}/requests |
support_macro_create |
Create a saved reply | write | support:write |
POST /api/v1/support/macros |
support_macro_delete |
Delete a saved reply | write (destructive) | support:write |
DELETE /api/v1/support/macros/{macro} |
support_macro_list |
List saved replies | read | support:read |
GET /api/v1/support/macros |
support_macro_update |
Change a saved reply | write | support:write |
PATCH /api/v1/support/macros/{macro} |
support_message_create |
Add an internal note | write | support:write |
POST /api/v1/support/conversations/{conversation}/messages |
support_message_list |
List a conversation's messages | read | support:read |
GET /api/v1/support/conversations/{conversation}/messages |
support_reply_send |
Send a reply to the customer | write | support:write |
POST /api/v1/support/conversations/{conversation}/reply |
support_report_get |
Support report | read | support:read |
GET /api/v1/support/report |
support_sla_policy_delete |
Delete an SLA policy | write (destructive) | support:write |
DELETE /api/v1/support/sla-policies/{policy} |
support_sla_policy_list |
List SLA policies | read | support:read |
GET /api/v1/support/sla-policies |
support_sla_policy_save |
Create or change an SLA policy | write | support:write |
POST /api/v1/support/sla-policies (+1) |
support_widget_get |
Chat widget and help center settings | read | support:read |
GET /api/v1/support/widget |
support_widget_save |
Change the chat widget and help center | write | support:write |
PATCH /api/v1/support/widget |
Related
- Venom Support: the inbox, replies, drafts from your notes and where conversations come from.
- Support email, SLA and reports and the chat widget.
- Org webhooks, Authentication and scopes and Errors, limits and pagination.