Reply to threads

Reply on a thread over whichever channel it already uses.

You can reply to a thread using the replyToThread mutation, as long as the thread’s communication channel is either API, CHAT, EMAIL, SLACK or ‘MS_TEAMS’. This information is available in the thread as the channel field.

For TypeScript, the GraphQL SDK gives you a fully typed client for these operations.

If it is not possible to reply to a thread, you will get the mutation error code cannot_reply_to_thread and a message indicating why.

This operation requires the following permissions:

• thread:reply

Mutation

mutation replyToThread($input: ReplyToThreadInput!) {
  replyToThread(input: $input) {
    error {
      message
      type
      code
    }
  }
}

Variables

{
  "input": {
    "threadId": "th_01H8H46YPB2S4MAJM382FG9423",
    "textContent": "The plain text version of your reply goes here.",
    "markdownContent": "The markdown **version** of your _reply_ goes here."
  }
}

Impersonation

Impersonation is exclusively available in our Frontier plan. You can see all available plans in our pricing page.

Reply as a customer

This feature allows you to bring native messaging between your customers and Plain, straight into your own product.

With impersonation, you can reply to a thread on behalf of one of your customers: impersonated messages will show up as if they were sent by the customers themselves.

In order to impersonate a customer, provide the impersonation parameter in the replyToThread mutation, specifying the identifier of the customer you want to impersonate. You can pick any of the available customer identifiers (emailAddress, customerId or externalId)

{
  "impersonation": {
    "asCustomer": {
      "customerIdentifier": {
        "emailAddress": "[e-mail]"
      }
    }
  }
}

Impersonation is only possible for API, CHAT, EMAIL and SLACK threads (based on the thread’s channel field).

The customer message will be processed differently based on the thread’s channel:

• SLACK: the message will appear in Slack as a new message from the impersonated customer, including their name and any other customer details
• API and EMAIL: the message will be sent as an email with the impersonated customer’s email address as the “From” address, making it appear as if they sent the email directly
• CHAT: the message will appear in the thread as coming directly from the impersonated customer, with their name and avatar displayed

When replying to an EMAIL or API thread, you can optionally add ‘Cc’ and ‘Bcc’ recipients by using the channelSpecificOptions parameter:

{
  "channelSpecificOptions": {
    "email": {
      // For CC'd recipients
      "additionalRecipients": [
        {
          "email": "[e-mail]",
          "name": "Peter"
        },
      ],
      // For BCC'd recipients
      "hiddenRecipients": [
        {
          "email": "[e-mail]"
        }
      ]
    }
  }
}

This operation requires the following permissions:

• thread:reply
• customer:impersonate

Mutation

mutation replyToThread($input: ReplyToThreadInput!) {
  replyToThread(input: $input) {
    error {
      message
      type
      code
    }
  }
}

Variables

{
  "input": {
    "threadId": "th_01H8H46YPB2S4MAJM382FG9423",
    "textContent": "Hi, I ran out of compute credits, how can I top them up?",
    "markdownContent": "Hi, I ran out of compute credits, how can I top them up?",
    "impersonation": {
      "asCustomer": {
        "customerIdentifier": {
          "emailAddress": "[e-mail]"
        }
      }
    },
    "channelSpecificOptions": {
      "email": {
        "hiddenRecipients": [
          {
            "email": "[e-mail]"
          }
        ]
      }
    }
  }
}

Reply as a user

Replying as a user sends the message from a team member. The customer sees that team member’s name instead of the machine user’s. Use this when an agent or automation replies on a team member’s behalf.

impersonation takes exactly one of asCustomer or asUser. Sending both, or neither, fails with input_validation. MS_TEAMS and DISCORD threads reject it with cannot_reply_to_thread.

Only an API key can reply as a user, and the key’s impersonation allow list must include that user. Set impersonation.asUser.userIdentifier to the user’s userId or emailAddress:

{
  "impersonation": {
    "asUser": {
      "userIdentifier": {
        "emailAddress": "[e-mail]"
      }
    }
  }
}

Each channel delivers the message differently:

• API and EMAIL: Plain sends the email from the user’s public name, the same as a reply the user sends from Plain
• CHAT: the message appears in the thread as sent by the user, with their name and avatar
• SLACK: Plain posts the message and any attachments through the user’s own Slack connection, as if the user sent it from Slack. If the user hasn’t connected Slack in Plain, the reply fails with missing_user_auth_slack_integration_for_team

In the thread’s timeline in Plain, the message shows the team member as its author, with a tag beside their name naming the machine user that sent it. In the API, the entry’s actor is the team member and its createdBy is the machine user.

The reply fails with one of these errors:

• cannot_reply_to_thread: the user isn’t on the API key’s allow list, the user’s role can’t reply to threads, or the caller isn’t a machine user with an API key
• not_found: the user doesn’t exist or has been removed from the workspace
• input_validation: the identifier names a machine user, or impersonation sets both targets or neither

This operation requires the following permissions:

• thread:reply

Mutation

mutation replyToThread($input: ReplyToThreadInput!) {
  replyToThread(input: $input) {
    error {
      message
      type
      code
    }
  }
}

Variables

{
  "input": {
    "threadId": "th_01H8H46YPB2S4MAJM382FG9423",
    "textContent": "Thanks for flagging this. I've topped up your credits.",
    "markdownContent": "Thanks for flagging this. I've topped up your credits.",
    "impersonation": {
      "asUser": {
        "userIdentifier": {
          "userId": "u_01H8H46YPB2S4MAJM382FG9423"
        }
      }
    }
  }
}