Interacting in discussions

A discussion is where users talk to your agent inside Plain. Any user can click Ask Sidekick from any page, pick your agent, and send a message. Plain sends you a webhook, and your agent replies through the API. Discussions are completely internal and not visible to your customers. A discussion can be attached to a thread or be standalone. When a user starts a discussion from a thread, the webhook payload will include discussion.threadId to tell you which thread the discussion is linked to. Discussions can also be started from a workflow. In the workflow builder you can pick your agent as well.

High-level flow

A user starts a discussion with your agent.
Plain sends discussion.message_created to your webhook target.
Your agent sets the discussion status to IN_PROGRESS, does its work, posts a reply, and sets IDLE.
Your agent can then log its tool calls as well as ask for a user’s approval. See tool calls for more info.

Permissions

For working with discussions, your machine user’s API key must have the following permissions:

threadDiscussion:read and threadDiscussion:edit to read discussions, report status, request approvals, resolve or reopen discussions
threadDiscussionMessage:create and threadDiscussionMessage:edit to post messages to the discussion
thread:read and customer:read if the agent needs to read the linked thread

Webhooks

Subscribe your webhook target to these events:

Event	When	Needed
`discussion.message_created`	A message was posted in any discussion	Always
`discussion.tool_call_approval_resolved`	A user approved or denied a tool call	If you ask for approvals
`discussion.turn_stop_requested`	A user asked your agent to stop	If you can stop mid-turn
`discussion.discussion_created`	A discussion was started	Optional. The first message is enough to start
`discussion.tool_call_approval_requested`	Echo of an approval you requested	Optional

Decide whether to answer

discussion.message_created fires for every discussion in the workspace, including your own replies. Answer only when all of these are true:

Condition	Why
`discussion.type` is `AGENT_SESSION`	Other types are Slack and email discussions between people.
`discussion.agent.id` is your machine user	Otherwise it is Sidekick or another agent.
`message.type` is `OUTBOUND`	A user’s message is `OUTBOUND`. Your replies come back as `INBOUND`.
`discussion.status` is not `RESOLVED`	Otherwise the discussion is over.

Load your machine user once at startup and deduplicate on message.id:

import { PlainClient } from "@team-plain/graphql";

const plain = new PlainClient({ apiKey: process.env.PLAIN_API_KEY! });
const me = await plain.query.myMachineUser();

function shouldAnswer(payload: DiscussionMessageCreatedPublicEventPayload) {
  return (
    payload.discussion.type === "AGENT_SESSION" &&
    payload.discussion.agent?.id === me.id &&
    payload.message.type === "OUTBOUND" &&
    payload.discussion.status !== "RESOLVED"
  );
}

In the webhook payload, message.markdown is what the user wrote. message.workspaceFiles lists any files they attached. You must respond with a status code of 200 before your agent starts work so that Plain doesn’t retry the webhook delivery.

Replying

You can use the sendDiscussionMessage mutation to reply to the discussion using markdown. This also marks the discussion as having unread messages within the Plain app.

SDK
GraphQL

import { PlainClient } from "@team-plain/graphql";

const plain = new PlainClient({ apiKey: process.env.PLAIN_API_KEY! });

const result = await plain.mutation.sendDiscussionMessage({
  input: {
    discussionId: "thd_01HZ8A1B2C3D4E5F6G7H8J9K0M",
    markdownContent:
      "The invoice failed because the card was **declined** on 3 September.",
  },
});

if (result.error) throw new Error(result.error.message);

Mutation

mutation sendDiscussionMessage($input: SendDiscussionMessageInput!) {
  sendDiscussionMessage(input: $input) {
    discussionMessage {
      id
    }
    error {
      message
      type
      code
    }
  }
}

Variables

{
  "input": {
    "discussionId": "thd_01HZ8A1B2C3D4E5F6G7H8J9K0M",
    "markdownContent": "The invoice failed because the card was **declined** on 3 September."
  }
}

Updating the discussion status

Set the discussion’s agent status to IN_PROGRESS when a turn starts and IDLE when it ends. If the turn fails, post the error as a message first, then set IDLE.

SDK
GraphQL

const result = await plain.mutation.updateDiscussionAgentStatus({
  input: {
    discussionId: "thd_01HZ8A1B2C3D4E5F6G7H8J9K0M",
    agentStatus: "IN_PROGRESS",
  },
});

if (result.error) throw new Error(result.error.message);

Mutation

mutation updateDiscussionAgentStatus($input: UpdateDiscussionAgentStatusInput!) {
  updateDiscussionAgentStatus(input: $input) {
    discussion {
      id
      agentStatus
    }
    error {
      message
      type
      code
    }
  }
}

Variables

{
  "input": {
    "discussionId": "thd_01HZ8A1B2C3D4E5F6G7H8J9K0M",
    "agentStatus": "IN_PROGRESS"
  }
}

Asking for a tool call approval will automatically update the discussion status to TOOL_CALL_APPROVAL_PENDING.When a discussion is pending a tool call approval, you cannot change its status manually.

Stop when asked

A user can stop your agent mid-turn. Plain sends discussion.turn_stop_requested with the discussion to stop. Cancel the model call, post what you have if useful, and set the discussion status to IDLE. The discussion stays open for the next message.

Resolve the discussion

You can use changeThreadDiscussionStatus to resolve a discussion when the user needs nothing further, or set the status to OPEN to reopen it.

SDK
GraphQL

const result = await plain.mutation.changeThreadDiscussionStatus({
  input: {
    threadDiscussionId: "thd_01HZ8A1B2C3D4E5F6G7H8J9K0M",
    status: "RESOLVED",
  },
});

if (result.error) throw new Error(result.error.message);

Mutation

mutation changeThreadDiscussionStatus($input: ChangeThreadDiscussionStatusInput!) {
  changeThreadDiscussionStatus(input: $input) {
    error {
      message
      type
      code
    }
  }
}

Variables

{
  "input": {
    "threadDiscussionId": "thd_01HZ8A1B2C3D4E5F6G7H8J9K0M",
    "status": "RESOLVED"
  }
}

Replying to customers on behalf of the user

A user in a discussion can ask your agent to message the customer. The agent can do this by calling the replyToThread mutation. By default the reply is from the machine user. To send it as the user who asked, add them to the API key’s impersonation allow list and pass impersonation.asUser. See reply as a user. The allow list belongs to the API key, not the machine user. Open the API key from the machine user’s page and, under Impersonation, add who it may reply as:

individual team members
everyone holding a built-in role: Owner, Admin, or Support
everyone holding a custom role

GraphQL API

Building Agents

Agent integrations

Webhooks

Channels

Customer Cards

UI Components

Security

Changelog

Interacting in discussions

High-level flow

Permissions

Webhooks

Decide whether to answer

Replying

Updating the discussion status

Stop when asked

Resolve the discussion

Replying to customers on behalf of the user

​High-level flow

​Permissions

​Webhooks

​Decide whether to answer

​Replying

​Updating the discussion status

​Stop when asked

​Resolve the discussion

​Replying to customers on behalf of the user

High-level flow

Permissions

Webhooks

Decide whether to answer

Replying

Updating the discussion status

Stop when asked

Resolve the discussion

Replying to customers on behalf of the user