Skip to content
Docs menu

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.

View .md

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 with support_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.breached and page someone, or read response and resolution times with GET /api/v1/support/report.
  • Saved replies kept in a repo. Sync your macros with support_macro_create, support_macro_update and support_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:read to use the tools and support:write to 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: false in 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_language and template_params for 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