diff --git a/README.md b/README.md index 4020a86..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: -**https://plain.com/docs** +[**plain.com/docs**](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/graphql/threads/autoresponders.mdx b/api-reference/graphql/threads/autoresponders.mdx new file mode 100644 index 0000000..b348c06 --- /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 fe69f5a..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). If you do, and you only care about emails which are not the - first message of the thread, please check the `isStartOfThread` 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 3cd1fac..dd1efce 100644 --- a/api-reference/webhooks/thread-email-received.mdx +++ b/api-reference/webhooks/thread-email-received.mdx @@ -4,13 +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`. 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. - - ## 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 aa6a6a5..270de15 100644 --- a/api-reference/webhooks/thread-email-sent.mdx +++ b/api-reference/webhooks/thread-email-sent.mdx @@ -4,13 +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`. 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. - - ## 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",