Rephrase webhook docs (#24)

* Rephrase webhook docs

* fix lint

* Update notice in email sent

* Move autoresponder documentation into dedicated page

* de-capitalise links

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"

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.
+
+<Warning>
+  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.
+</Warning>
+
+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.

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.
-
-<Warning>
-  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.
-</Warning>
+You can subscribe to this event if you want to build an [autoresponder](/api-reference/graphql/threads/autoresponders).
 
 ## Schema
 

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.
 
-<Warning>
-  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.
-</Warning>
-
 ## Schema
 
 [**View JSON Schema →**](https://json-schema.app/view/%23%2Fdefinitions%2FcustomerCreatedPayload?url=https%3A%2F%2Fcore-api.uk.plain.com%2Fwebhooks%2Fschema.json)

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.
 
-<Warning>
-  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.
-</Warning>
-
 ## Schema
 
 [**View JSON Schema →**](https://json-schema.app/view/%23%2Fdefinitions%2FcustomerCreatedPayload?url=https%3A%2F%2Fcore-api.uk.plain.com%2Fwebhooks%2Fschema.json)

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.
 
 <Warning>
-  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.
 </Warning>
+
+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.

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",