Manage shared-inbox tickets and conversations in GrooveHQ via the v2 GraphQL API.

Provided free and as is, without warranty of any kind — including merchantability, fitness for a particular purpose, and the accuracy or completeness of any result. See the licence. You are responsible for checking what this produces before relying on it.

Groove

Manage shared-inbox tickets and conversations in GrooveHQ using the v2 GraphQL API (https://api.groovehq.com/v2/graphql).

What It Does

Operation	Description
`list_conversations`	List recent conversations (newest first), with subject, state, message counts.
`get_conversation`	Fetch full details for a single conversation by ID, including assignment, tags, and counts.
`create_conversation`	Open a new outbound email conversation in a specific channel.
`close_conversation`	Close an open conversation by ID.

API Key Setup

GrooveHQ v2 uses a Bearer token. Obtain one via the v1 REST authentication endpoint:

POST https://api.groovehq.com/v1/authorize.json
Content-Type: application/json

{
  "user": {
    "email": "[email protected]",
    "password": "yourpassword",
    "subdomain": "yourcompany",
    "mobile": true
  }
}

Copy the token field from the response. Use it as the apiKey input to this tool.

Note: tokens do not expire automatically but can be revoked from the Groove admin panel.

Inputs

Input	Required	Description
`apiKey`	Yes	Bearer token from the v1 authorize endpoint.
`operation`	Yes	One of: `list_conversations`, `get_conversation`, `create_conversation`, `close_conversation`.
`conversationId`	For `get_conversation`, `close_conversation`	Groove conversation ID, e.g. `cnv_12345678`.
`channelId`	For `create_conversation`	Groove channel ID, e.g. `ch_12345678`. Find it via the Groove admin or the GraphQL `channels` query.
`toEmail`	For `create_conversation`	Recipient email address.
`toName`	For `create_conversation`	Recipient display name (optional).
`subject`	For `create_conversation`	Email subject line.
`body`	For `create_conversation`	Email body text.
`pageSize`	For `list_conversations`	Number of conversations to return (1–100, default 25).

Outputs

Output	Description
`result`	Raw JSON response body from the GraphQL API.
`status`	HTTP status code as a string (200 on success).

Examples

List the 10 most recent conversations:

operation: list_conversations
pageSize: 10

Get full details for a conversation:

operation: get_conversation
conversationId: cnv_12345678

Create a new email conversation:

operation: create_conversation
channelId: ch_4567890
toEmail: [email protected]
toName: Jane Smith
subject: Your order has shipped
body: Hi Jane, your order #1234 has shipped and will arrive in 3–5 business days.

Close a conversation:

operation: close_conversation
conversationId: cnv_12345678

Publishes

The keys a later task may reference as {{taskName.key}}. Referencing anything not listed here resolves to nothing at run time.

error
result
status

Input Properties

Every property this tool accepts, from its own tool.iml.

Property	Type	Required	Default	Description
`apiKey`	string	yes	—	Groove Bearer access token. Obtain by posting your email+password+subdomain to https://api.groovehq.com/v1/authorize.json and copying the 'token' field from the response.
`operation`	string	yes	—	One of: list_conversations, get_conversation, create_conversation, close_conversation
`conversationId`	string	no	—	Groove conversation ID (e.g. cnv_12345678). Required for get_conversation and close_conversation.
`channelId`	string	no	—	Groove channel ID (e.g. ch_12345678). Required for create_conversation.
`toEmail`	string	no	—	Recipient email address for create_conversation (e.g. [email protected]). Required.
`toName`	string	no	—	Recipient display name for create_conversation. Optional.
`subject`	string	no	—	Email subject for create_conversation. Required.
`pageSize`	string	no	—	Number of conversations to return for list_conversations (default 25, max 100).