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.

mutation SendMessage($input: SendMessageInput!) {
  sendMessage(input: $input) {
    thread {
      id
      subject
    }
    message {
      id
      text
    }
  }
}

With variables, a payload looks like this:

{
  "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.

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:

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.

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.

{
  "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.

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.

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.

mutation SendMessage($input: SendMessageInput!) {
  sendMessage(input: $input) {
    thread {
      id
      subject
    }
    message {
      id
      text
    }
  }
}

With variables:

{
  "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.

{
  "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.

{
  "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.

{
  "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 documentation for detailed information on how to upload files.

Once you have file IDs for the attachments, you can include them in your message:

mutation SendMessage($input: SendMessageInput!) {
  sendMessage(input: $input) {
    thread {
      id
      subject
    }
    message {
      id
      text
      attachments {
        ... on File {
          id
          name
        }
      }
    }
  }
}

With variables:

{
  "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.