P-7954: Document impersonation in replyToThread (#71)

* ReplyToThread impersonation * linting --------- Co-authored-by: Mathias Vagni <[email protected]>
team-plain · Jul 23, 2024 · d28df01 · d28df01
1 parent 64a7b6b
commit d28df01
Show file tree

Hide file tree

Showing 3 changed files with 149 additions and 9 deletions.
diff --git a/_snippets/graphql/reply-to-thread-impersonation.mdx b/_snippets/graphql/reply-to-thread-impersonation.mdx
@@ -0,0 +1,37 @@
+```graphql Mutation
+mutation replyToThread($input: ReplyToThreadInput!) {
+  replyToThread(input: $input) {
+    error {
+      message
+      type
+      code
+    }
+  }
+}
+```
+
+```json 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": "[email protected]"
+        }
+      }
+    },
+    "channelSpecificOptions": {
+      "email": {
+        "hiddenRecipients": [
+          {
+            "email": "[email protected]"
+          }
+        ]
+      }
+    }
+  }
+}
+```
diff --git a/_snippets/typescript-sdk/reply-to-thread-impersonation.mdx b/_snippets/typescript-sdk/reply-to-thread-impersonation.mdx
@@ -0,0 +1,33 @@
+```ts
+import { PlainClient } from '@team-plain/typescript-sdk';
+
+const client = new PlainClient({ apiKey: 'plainApiKey_xxx' });
+
+const res = await client.replyToThread({
+  threadId: 'th_01HD1G6649R1DK061W27VBT7QB',
+  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: '[email protected]',
+      },
+    },
+  },
+  additionalChannelOptions: {
+    email: {
+      hiddenRecipients: [
+        {
+          email: '[email protected]',
+        },
+      ],
+    },
+  },
+});
+
+if (res.error) {
+  console.error(res.error);
+} else {
+  console.log(res.data);
+}
+```
diff --git a/api-reference/graphql/messaging/reply-to-thread.mdx b/api-reference/graphql/messaging/reply-to-thread.mdx
@@ -2,31 +2,101 @@
 title: 'Reply to threads'
 ---
 
-You can reply to a thread using the `replyToThread` mutation. This will work regardless if the last email in the thread is from a user or a customer.
+You can reply to a thread using the `replyToThread` mutation, as long as the thread's communication channel is either `EMAIL` or `SLACK`. This information is available in the thread as the `channel` field.
 
-If it is not possible to reply to this thread, you will get the mutation error code [`cannot_reply_to_thread`](/api-reference/graphql/error-codes#cannot_reply_to_thread) and a message indicating why.
+If it is not possible to reply to a thread, you will get the mutation error code [`cannot_reply_to_thread`](/api-reference/graphql/error-codes#cannot_reply_to_thread) and a message indicating why.
+
+This operation requires the following permission:
+
+- `thread:reply`
 
 <Tabs>
   <Tab title="Typescript SDK">
-      Only one permission is needed:
-
-      - `thread:reply`
 
       <Snippet file="typescript-sdk/reply-to-thread.mdx" />
 
       Where `res.data` is:
 
       <Snippet file="typescript-sdk/reply-to-thread-response.mdx" />
 
-      </Tab>
+</Tab>
 
   <Tab title="GraphQL">
-    Only one permission is needed:
-
-    - `thread:reply`
 
     <Snippet file="graphql/reply-to-thread.mdx" />
 
   </Tab>
 
 </Tabs>
+
+## Impersonation
+
+<Note>
+  Impersonation is exclusively available in our `Scale` plan. You can see all available plans in our
+  [pricing page](https://www.plain.com/pricing).
+</Note>
+
+This feature allows you to bring native messaging between your customers and Plain, straight into [your own product](/api-reference/headless-portal).
+
+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`)
+
+```graphql
+{
+  "impersonation": {
+    "asCustomer": {
+      "customerIdentifier": {
+        "emailAddress": "[email protected]"
+      }
+    }
+  }
+}
+```
+
+The customer message will be processed differently based on the thread's channel:
+
+- `SLACK`: a new Slack message will be sent to the thread, using the customer's details
+- `EMAIL`: an email will be sent to the thread, where the sender will be your customer
+
+When replying to an `EMAIL` thread, you can optionally add 'CC' and 'BCC' recipients by using the `channelSpecificOptions` parameter:
+
+```graphql
+{
+  "channelSpecificOptions": {
+    "email": {
+      // For CC'd recipients
+      "additionalRecipients": [
+        {
+          "email": "[email protected]",
+          "name": "Peter"
+        },
+      ],
+      // For BCC'd recipients
+      "hiddenRecipients": [
+        {
+          "email": "[email protected]"
+        }
+      ]
+    }
+  }
+}
+```
+
+This operation requires the following permissions:
+
+- `thread:reply`
+- `customer:impersonate`
+
+<Tabs>
+  <Tab title="Typescript SDK">
+
+      <Snippet file="typescript-sdk/reply-to-thread-impersonation.mdx" />
+
+</Tab>
+
+    <Tab title="GraphQL">
+
+      <Snippet file="graphql/reply-to-thread-impersonation.mdx" />
+      </Tab>
+</Tabs>