# Sending messages Sending a message is the core building block of any Glue integration. Whether you’re writing a bot that reports issues, an app that posts status updates, or just testing the API, the `sendMessage` mutation is the place to start. ## The `sendMessage` mutation The `sendMessage` mutation allows you to: * Send a message to an **existing thread** (using a `threadID`) * Create a **new thread** (by providing a thread object with configuration) Here is a basic example that sends a message to an existing thread with ID `thr_2hSyORgf8VqMLg0ADIvTi9oY6Nk`. ```graphql mutation SendMessage($input: SendMessageInput!) { sendMessage(input: $input) { thread { id subject } message { id text } } } ``` With variables, a payload looks like this: ```json { "input": { "threadID": "thr_2hSyORgf8VqMLg0ADIvTi9oY6Nk", "message": { "text": "New bug reported!" } } } ``` ### First, find a Thread ID To send a message into an existing thread, you’ll need its ID. * Open the thread in the Glue app. * Select **Copy share link** from the menu. * Look in the URL: * Thread IDs begin with `thr_...` * Group IDs begin with `grp_...` Example URL: ``` https://app.gluegroups.com/thr_2hSyORgf8VqMLg0ADIvTi9oY6Nk?t=Chat ``` Here the thread ID is: ``` thr_2hSyORgf8VqMLg0ADIvTi9oY6Nk ``` Use this value as the `threadID` in your mutation input. ### SendMessage mutation input Here are the fields that you can send to the `sendMessage` mutation. These fields should be sent as GraphQL variables. | Field | Description | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `threadID` | Optional. The ID of an existing thread to send to. If provided, the message will be sent to this thread. | | `thread` | Optional. Thread configuration for creating a new thread or updating an existing one. Must be provided if `threadID` is not specified. | | `message` | Required. The message to send. | #### ThreadInput fields | Field | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `recipients` | Required. Array of recipient IDs (users, groups, or workspace). For a group, a message will be sent to the chat unless a `subject` is specified - in this case a thread will be created in the group instead. | | `subject` | If specified, a thread will be created instead of just sending a message. The `recipients` must be a group if a subject is specified. | | `threadBy` | Specify a value here to be able to update this thread after it is created. If you call the mutation again with the same value, it will update the existing thread instead of generating a new one. | | `replyToMessageID` | Optional. The ID of a message to reply to. | #### MessageInput fields | Field | Description | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | Required. The text of the message to send. By default, this is treated as markdown. | | `attachments` | Optional. Array of file IDs to attach to the message. | | `uniqueBy` | Specify a value here to be able to update this message after it is created. If you call the mutation again with the same value, it will update the existing message instead of generating a new one. | | `quotedMessageID` | Optional. The ID of a message to quote in this message. | *** ## Example: Sending a message to an existing thread To send a message to an existing thread, provide a `threadID` and a `message` input with the message text. ```graphql mutation SendMessage($input: SendMessageInput!) { sendMessage(input: $input) { thread { id subject } message { id text } } } ``` ### Quick Test with curl Try a quick test, and `curl` right from your terminal: ```bash curl https://api.gluegroups.com/graphql \ -H "Authorization: Bearer $GLUE_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "query": "mutation SendMessage($input: SendMessageInput!) { sendMessage(input: $input) { thread { id subject } message { id text } } }", "variables": { "input": { "threadID": "thr_[YOUR ID HERE]", "message": { "text": "Hello World 👋" } } } }' ``` If you need help generating an access token, check out the [OAuth 2.0 Authentication guide](/developers/authentication/oauth-2-0-authentication.md). ## Example: Editing an Existing Message with `uniqueBy` Often, integrations need to *revise* a message — for example, updating the status of a bug report. To do this, include a `uniqueBy` tag. * Using the same `uniqueBy` updates the message. * Using a new `uniqueBy` creates a new message. To update the previously sent message, call the mutation again with the same `uniqueBy` value. ```json { "input": { "threadID": "thr_2hTJ4DGsxUAeEhKOyJ2PMePFL0c", "message": { "text": "New bug reported: [BUG154](https://example.com/BUG154) \n\nResolved by Jason", "uniqueBy": "BUG154" } } } ``` To generate a new message, simply provide a new `uniqueBy` value, or omit the `uniqueBy` value if you will not need to update the message. {% hint style="info" %} The `uniqueBy` can be any unique string, but it's a great way to map IDs of another service, such as bug, issue, project, or incident IDs. {% endhint %} ## Example: Creating threads To create a thread instead of just sending a message, provide a `thread` object with `recipients`, `subject`, and optionally a `threadBy` value. This will result in a thread created among the specified recipients and the app with the subject and starter message from `message.text`. ```graphql mutation SendMessage($input: SendMessageInput!) { sendMessage(input: $input) { thread { id subject } message { id text } } } ``` With variables: ```json { "input": { "thread": { "recipients": ["grp_2hSyORgf8VqMLg0ADIvTi9oY6Nk"], "subject": "New crash in main.js", "threadBy": "BUG268" }, "message": { "text": "ReferenceError: reference to undefined property x", "uniqueBy": "BUG268-starter-message" } } } ``` When you specify an `threadBy` value in the thread, you can send follow up messages to the thread by calling the mutation again with the same `threadBy` value. This is perfect for linking threads to your issue tracking system or project management tool. In this case we're using the value `BUG268`. ```json { "input": { "thread": { "recipients": ["grp_2hSyORgf8VqMLg0ADIvTi9oY6Nk"], "subject": "New crash in main.js", "threadBy": "BUG268" }, "message": { "text": "Jason, can you look into this?" } } } ``` Because we specified a `uniqueBy` value for the starter message, we can call the mutation again to update that starter message. Here we're using `"uniqueBy": "BUG268-starter-message"` which is the value we passed in the first mutation to start the thread. ```json { "input": { "thread": { "recipients": ["grp_2hSyORgf8VqMLg0ADIvTi9oY6Nk"], "subject": "New crash in main.js", "threadBy": "BUG268" }, "message": { "text": "ReferenceError: reference to undefined property x \n\nAssigned to: Jason", "uniqueBy": "BUG268-starter-message" } } } ``` To create a different thread, send a new `threadBy` value or, if the `threadBy` value is omitted, a new thread will always be created. ```json { "input": { "thread": { "recipients": ["grp_2hSyORgf8VqMLg0ADIvTi9oY6Nk"], "subject": "New crash in index.js", "threadBy": "BUG269" }, "message": { "text": "ReferenceError: reference to undefined property y", "uniqueBy": "BUG269-starter-message" } } } ``` ## Example: Attachments To send a message with attachments, you'll need to upload files first using the attachments API. See the [Attachments](/developers/graphql-api/attachments.md) documentation for detailed information on how to upload files. Once you have file IDs for the attachments, you can include them in your message: ```graphql mutation SendMessage($input: SendMessageInput!) { sendMessage(input: $input) { thread { id subject } message { id text attachments { ... on File { id name } } } } } ``` With variables: ```json { "input": { "threadID": "thr_2kbzWHxtQvfVEgwEdQduuxRTYG3", "message": { "text": "New report available!", "attachments": ["fil_2ymM4HRuRY4A7ed8OvVaUYxQ812"] } } } ``` You can attach up to 10 files per message. *** ## Summary You now know how to: * Find a thread ID * Send a basic message * Update a message with `uniqueBy` * Create new threads * Add attachments These are the core concepts you’ll use in any Glue integration. From here, you can start building bots, automation, and workflows that connect your systems directly into Glue conversations. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.glue.ai/developers/graphql-api/messages_and_threading.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.