From 0e1e452988b9768bdabb8e9eebf29ffd04f11de6 Mon Sep 17 00:00:00 2001 From: David Leyland Date: Mon, 12 Feb 2024 16:28:19 +0000 Subject: [PATCH 1/5] Rephrase webhook docs --- README.md | 6 +++--- api-reference/webhooks/thread-created.mdx | 4 ++-- api-reference/webhooks/thread-email-received.mdx | 9 +++++---- 3 files changed, 10 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 4020a86..65ecd65 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ This is the documentation for [Plain](https://plain.com) and its API which you can find here: -**https://plain.com/docs** +**** They are built using [Mintlify](https://mintlify.com). @@ -24,5 +24,5 @@ There are some key language/style choices you should follow (and add to): - URL is uppercase - 'backend' not 'back-end' - Be consistent in which words are used for different groups of people: - - When refering to people who are helped via Plain use the name "customer" - - When refering to people who use Plain to help other people use the name "user" + - When referring to people who are helped via Plain use the name "customer" + - When referring to people who use Plain to help other people use the name "user" diff --git a/api-reference/webhooks/thread-created.mdx b/api-reference/webhooks/thread-created.mdx index fe69f5a..619a185 100644 --- a/api-reference/webhooks/thread-created.mdx +++ b/api-reference/webhooks/thread-created.mdx @@ -11,8 +11,8 @@ You can subscribe to this event **if you want to build an auto-responder**. To d thread for an email, we will create one. When this happens, you may receive two events: `thread.thread_created` and [`thread.email_received`](/api-reference/webhooks/thread-email-received) (depending on your - webhook target event subscriptions). If you do, and you only care about emails which are not the - first message of the thread, please check the `isStartOfThread` in the + webhook target event subscriptions). In order to avoid replying to the same thread twice if you + subscribe to both events, please check the `isStartOfThread` field in the [`thread.email_received`](/api-reference/webhooks/thread-email-received) payload. diff --git a/api-reference/webhooks/thread-email-received.mdx b/api-reference/webhooks/thread-email-received.mdx index 3cd1fac..3304a13 100644 --- a/api-reference/webhooks/thread-email-received.mdx +++ b/api-reference/webhooks/thread-email-received.mdx @@ -5,10 +5,11 @@ title: 'Email received' This event is fired when an email is received in your workspace. - An important field that might go unnoticed is `isStartOfThread`. This will tell you if this email - is the first message of a thread or not, which is useful if you want to build some auto-reply - logic. If you want to build an auto-responder that *only replies* to the first message of a - thread, please check [`thread.thread_created`](/api-reference/webhooks/thread-created) instead. + An important field that might go unnoticed is `isStartOfThread` which tells you if this email is + the first message of a thread or not. This is useful if you want to build some auto-reply logic + but note that this will only work for responding to threads received via email. If you want to + reply to all threads (including Slack messages and anything received via the API) please check + [`thread.thread_created`](/api-reference/webhooks/thread-created) instead. ## Schema From 31ae1e3cda42c5109f0088e838b13a442bf80851 Mon Sep 17 00:00:00 2001 From: David Leyland Date: Mon, 12 Feb 2024 16:54:03 +0000 Subject: [PATCH 2/5] fix lint --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 65ecd65..e4aca9c 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ This is the documentation for [Plain](https://plain.com) and its API which you can find here: -**** +[**plain.com/docs**](https://plain.com/docs) They are built using [Mintlify](https://mintlify.com). From 1ba149301c61963659a16a3e6b13044f08317444 Mon Sep 17 00:00:00 2001 From: David Leyland Date: Mon, 12 Feb 2024 16:55:01 +0000 Subject: [PATCH 3/5] Update notice in email sent --- api-reference/webhooks/thread-email-sent.mdx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/api-reference/webhooks/thread-email-sent.mdx b/api-reference/webhooks/thread-email-sent.mdx index aa6a6a5..a43de70 100644 --- a/api-reference/webhooks/thread-email-sent.mdx +++ b/api-reference/webhooks/thread-email-sent.mdx @@ -5,10 +5,11 @@ title: 'Email sent' This event is fired when an email is sent in your workspace. - An important field that might go unnoticed is `isStartOfThread`. This will tell you if this email - is the first message of a thread or not, which is useful if you want to build some auto-reply - logic. If you want to build an auto-responder that *only replies* to the first message of a - thread, please check [`thread.thread_created`](/api-reference/webhooks/thread-created) instead. + An important field that might go unnoticed is `isStartOfThread` which tells you if this email is + the first message of a thread or not. This is useful if you want to build some auto-reply logic + but note that this will only work for responding to threads received via email. If you want to + reply to all threads (including Slack messages and anything received via the API) please check + [`thread.thread_created`](/api-reference/webhooks/thread-created) instead. ## Schema From db6c6b8cd89dddd34ef89567552127c482c5b366 Mon Sep 17 00:00:00 2001 From: David Leyland Date: Tue, 13 Feb 2024 11:27:43 +0000 Subject: [PATCH 4/5] Move autoresponder documentation into dedicated page --- .../graphql/threads/autoresponders.mdx | 18 ++++++++++++++++++ api-reference/webhooks/thread-created.mdx | 12 +----------- .../webhooks/thread-email-received.mdx | 8 -------- api-reference/webhooks/thread-email-sent.mdx | 8 -------- autoresponders.mdx | 4 +++- mint.json | 3 ++- 6 files changed, 24 insertions(+), 29 deletions(-) create mode 100644 api-reference/graphql/threads/autoresponders.mdx diff --git a/api-reference/graphql/threads/autoresponders.mdx b/api-reference/graphql/threads/autoresponders.mdx new file mode 100644 index 0000000..d1ab55c --- /dev/null +++ b/api-reference/graphql/threads/autoresponders.mdx @@ -0,0 +1,18 @@ +--- +Autoresponders +--- + +Plain provides a native [workspace level autoresponder](/autoresponders), however for more complex cases you may want to implement your own custom autoresponder. + +To achieve this you can set up endpoint(s) to be notified of one or more [Webhooks](/api-reference/webhooks) from Plain. We would typically recommend listening for the [Thread created](/api-reference/webhooks/thread-created) webhook as this will allow you the option of responding to any Thread whether it was created via email, Slack or a contact form. + +If you want to only reply to emails, you can use the [Email received](/api-reference/webhooks/thread-email-received) webhook. This will trigger for all emails, not just the first one in a thread, so you should check the `isStartOfThread` field provided in the webhook payload to ensure you only reply to the first message. + + + Note that if you subscribe to both `thread.thread_created` and `thread.email_received` you may + receive two events for the same email, since we create a new thread for emails which don't belong + to an existing thread. In order to avoid replying to the same message twice please check the + `isStartOfThread` field in the `thread.email_received` payload. + + +Once you have received an event and decided how to respond you can use the `replyToThread` mutation to send a reply back to the customer. See our [API explorer](https://app.plain.com/developer/api-explorer/) or [Typescript SDK](https://github.com/team-plain/typescript-sdk/) for more details. diff --git a/api-reference/webhooks/thread-created.mdx b/api-reference/webhooks/thread-created.mdx index 619a185..4968438 100644 --- a/api-reference/webhooks/thread-created.mdx +++ b/api-reference/webhooks/thread-created.mdx @@ -4,17 +4,7 @@ title: 'Thread created' This event is fired when a new thread is created in your workspace. -You can subscribe to this event **if you want to build an auto-responder**. To do so, when you receive this event, use the `replyToThread` mutation to send a reply back to the customer. - - - Every email you receive in your workspace is linked to a thread. If we cannot find a matching - thread for an email, we will create one. When this happens, you may receive two events: - `thread.thread_created` and - [`thread.email_received`](/api-reference/webhooks/thread-email-received) (depending on your - webhook target event subscriptions). In order to avoid replying to the same thread twice if you - subscribe to both events, please check the `isStartOfThread` field in the - [`thread.email_received`](/api-reference/webhooks/thread-email-received) payload. - +You can subscribe to this event if you want to build an [autoresponder](/api-reference/graphql/threads/autoresponders). ## Schema diff --git a/api-reference/webhooks/thread-email-received.mdx b/api-reference/webhooks/thread-email-received.mdx index 3304a13..dd1efce 100644 --- a/api-reference/webhooks/thread-email-received.mdx +++ b/api-reference/webhooks/thread-email-received.mdx @@ -4,14 +4,6 @@ title: 'Email received' This event is fired when an email is received in your workspace. - - An important field that might go unnoticed is `isStartOfThread` which tells you if this email is - the first message of a thread or not. This is useful if you want to build some auto-reply logic - but note that this will only work for responding to threads received via email. If you want to - reply to all threads (including Slack messages and anything received via the API) please check - [`thread.thread_created`](/api-reference/webhooks/thread-created) instead. - - ## Schema [**View JSON Schema →**](https://json-schema.app/view/%23%2Fdefinitions%2FcustomerCreatedPayload?url=https%3A%2F%2Fcore-api.uk.plain.com%2Fwebhooks%2Fschema.json) diff --git a/api-reference/webhooks/thread-email-sent.mdx b/api-reference/webhooks/thread-email-sent.mdx index a43de70..270de15 100644 --- a/api-reference/webhooks/thread-email-sent.mdx +++ b/api-reference/webhooks/thread-email-sent.mdx @@ -4,14 +4,6 @@ title: 'Email sent' This event is fired when an email is sent in your workspace. - - An important field that might go unnoticed is `isStartOfThread` which tells you if this email is - the first message of a thread or not. This is useful if you want to build some auto-reply logic - but note that this will only work for responding to threads received via email. If you want to - reply to all threads (including Slack messages and anything received via the API) please check - [`thread.thread_created`](/api-reference/webhooks/thread-created) instead. - - ## Schema [**View JSON Schema →**](https://json-schema.app/view/%23%2Fdefinitions%2FcustomerCreatedPayload?url=https%3A%2F%2Fcore-api.uk.plain.com%2Fwebhooks%2Fschema.json) diff --git a/autoresponders.mdx b/autoresponders.mdx index 4755f8b..62730d3 100644 --- a/autoresponders.mdx +++ b/autoresponders.mdx @@ -9,5 +9,7 @@ An autoresponder can be useful in situations of acute support load, such as duri Autoresponder messages are best kept short and personable without too many links or formatting. Messages which are too long and scripted will often just be ignored as they are too obviously automated. - Please be aware that autresponders are not yet supported for threads created via Slack. + Please be aware that autoresponders are not yet supported for threads created via Slack. + +You can also leverage Plain's powerful API and webhooks to build custom interactive autoresponders, see [Thread autoresponders](/api-reference/graphql/threads/autoresponders) for more details. diff --git a/mint.json b/mint.json index aba21b4..89152f7 100644 --- a/mint.json +++ b/mint.json @@ -151,7 +151,8 @@ "api-reference/graphql/threads", "api-reference/graphql/threads/create", "api-reference/graphql/threads/assignment", - "api-reference/graphql/threads/status-changes" + "api-reference/graphql/threads/status-changes", + "api-reference/graphql/threads/autoresponders" ] }, "api-reference/graphql/pagination", From f65273e8d07a175630b51012e0756cd60c69ede8 Mon Sep 17 00:00:00 2001 From: David Leyland Date: Tue, 13 Feb 2024 11:44:13 +0000 Subject: [PATCH 5/5] de-capitalise links --- api-reference/graphql/threads/autoresponders.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api-reference/graphql/threads/autoresponders.mdx b/api-reference/graphql/threads/autoresponders.mdx index d1ab55c..b348c06 100644 --- a/api-reference/graphql/threads/autoresponders.mdx +++ b/api-reference/graphql/threads/autoresponders.mdx @@ -4,9 +4,9 @@ Autoresponders Plain provides a native [workspace level autoresponder](/autoresponders), however for more complex cases you may want to implement your own custom autoresponder. -To achieve this you can set up endpoint(s) to be notified of one or more [Webhooks](/api-reference/webhooks) from Plain. We would typically recommend listening for the [Thread created](/api-reference/webhooks/thread-created) webhook as this will allow you the option of responding to any Thread whether it was created via email, Slack or a contact form. +To achieve this you can set up endpoint(s) to be notified of one or more [webhooks](/api-reference/webhooks) from Plain. We would typically recommend listening for the [thread created](/api-reference/webhooks/thread-created) webhook as this will allow you the option of responding to any Thread whether it was created via email, Slack or a contact form. -If you want to only reply to emails, you can use the [Email received](/api-reference/webhooks/thread-email-received) webhook. This will trigger for all emails, not just the first one in a thread, so you should check the `isStartOfThread` field provided in the webhook payload to ensure you only reply to the first message. +If you want to only reply to emails, you can use the [email received](/api-reference/webhooks/thread-email-received) webhook. This will trigger for all emails, not just the first one in a thread, so you should check the `isStartOfThread` field provided in the webhook payload to ensure you only reply to the first message. Note that if you subscribe to both `thread.thread_created` and `thread.email_received` you may