> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humanly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Message Groups

> Create and manage message groups for interview invites and communications

## Overview

Message groups contain templates for SMS and email messages sent to candidates during the interview process. You can create message groups with custom messaging for different interview types (standard or questionnaire) and control when messages are sent.

## List Message Groups

List available message groups for your organization/team.

**Endpoint:** `GET /qsi/gather/message-groups`

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET https://api.prod.qualifi.hr/qsi/gather/message-groups \
      -H "x-api-key: ${API_KEY}"
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch('https://api.prod.qualifi.hr/qsi/gather/message-groups', {
      headers: {
        'x-api-key': apiKey
      }
    });
    const messageGroups = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.get(
        'https://api.prod.qualifi.hr/qsi/gather/message-groups',
        headers={'x-api-key': api_key}
    )
    messageGroups = response.json()
    ```
  </Tab>
</Tabs>

<CodeGroup>
  ```json Response theme={null}
  {
    "data": {
      "messageGroups": [
        {
          "id": "message-group-uuid",
          "title": "Standard Interview Messages",
          "status": "PUBLISHED",
          "type": "standard",
          "default": true,
          "organizationId": "org-uuid",
          "teamId": "team-uuid",
          "createdById": "user-uuid",
          "createdAt": "2024-01-01T00:00:00Z",
          "updatedAt": "2024-01-01T00:00:00Z",
          "archivedAt": null
        }
      ]
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## Get Message Group

Get message group details including all messages.

**Endpoint:** `GET /qsi/gather/message-groups/{messageGroupId}`

<ParamField path="messageGroupId" type="string" required>
  UUID of the message group
</ParamField>

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET https://api.prod.qualifi.hr/qsi/gather/message-groups/{messageGroupId} \
      -H "x-api-key: ${API_KEY}"
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch(
      `https://api.prod.qualifi.hr/qsi/gather/message-groups/${messageGroupId}`,
      {
        headers: {
          'x-api-key': apiKey
        }
      }
    );
    const messageGroup = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.get(
        f'https://api.prod.qualifi.hr/qsi/gather/message-groups/{message_group_id}',
        headers={'x-api-key': api_key}
    )
    messageGroup = response.json()
    ```
  </Tab>
</Tabs>

<CodeGroup>
  ```json Response theme={null}
  {
    "data": {
      "messageGroup": {
        "id": "message-group-uuid",
        "title": "Standard Interview Messages",
        "status": "PUBLISHED",
        "type": "standard",
        "default": false,
        "organizationId": "org-uuid",
        "teamId": "team-uuid",
        "createdById": "user-uuid",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z",
        "archivedAt": null,
        "messages": [
          {
            "id": "message-uuid-1",
            "type": "INVITE",
            "smsBody": "You've been invited to complete an interview. Click here: {{link}}",
            "smsEnabled": true,
            "emailSubject": "Interview Invitation",
            "emailHeader": "You've been invited!",
            "emailBody": "Please complete your interview by clicking the link below.",
            "emailEnabled": true,
            "messageGroupId": "message-group-uuid",
            "createdAt": "2024-01-01T00:00:00Z",
            "updatedAt": "2024-01-01T00:00:00Z"
          }
        ]
      }
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## Create Message Group

Create a new message group with messages for a team. Message groups can be of type 'standard' or 'questionnaire' and can be in 'DRAFT' or 'PUBLISHED' status.

**Endpoint:** `POST /qsi/gather/message-groups`

<ParamField name="title" type="string" required>
  Title of the message group
</ParamField>

<ParamField name="type" type="string" required>
  Type: `"standard"` or `"questionnaire"`
</ParamField>

<ParamField name="status" type="string" required>
  Status: `"DRAFT"` or `"PUBLISHED"`
</ParamField>

<ParamField name="teamId" type="string" required>
  UUID of the team
</ParamField>

<ParamField name="default" type="boolean">
  Whether this is the default message group (default: false)
</ParamField>

<ParamField name="messages" type="array" required>
  Array of message objects
</ParamField>

<ParamField name="messages[].type" type="string" required>
  Message type: `"INVITE"`, `"CANDIDATE_REMINDER"`, or
  `"COMPLETION_CONFIRMATION"`
</ParamField>

<ParamField name="messages[].smsBody" type="string">
  SMS message body (use `{{ link }}` for interview link)
</ParamField>

<ParamField name="messages[].smsEnabled" type="boolean">
  Whether SMS is enabled for this message type
</ParamField>

<ParamField name="messages[].emailSubject" type="string">
  Email subject line
</ParamField>

<ParamField name="messages[].emailHeader" type="string">
  Email header text
</ParamField>

<ParamField name="messages[].emailBody" type="string">
  Email body text
</ParamField>

<ParamField name="messages[].emailEnabled" type="boolean">
  Whether email is enabled for this message type
</ParamField>

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.prod.qualifi.hr/qsi/gather/message-groups \
      -H "x-api-key: ${API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "title": "Standard Interview Messages",
        "type": "standard",
        "status": "DRAFT",
        "teamId": "team-uuid",
        "messages": [
          {
            "type": "INVITE",
            "smsBody": "You have been invited to complete an interview.",
            "smsEnabled": true,
            "emailSubject": "Interview Invitation",
            "emailHeader": "You'\''ve been invited!",
            "emailBody": "Please complete your interview.",
            "emailEnabled": true
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch('https://api.prod.qualifi.hr/qsi/gather/message-groups', {
      method: 'POST',
      headers: {
        'x-api-key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        title: 'Standard Interview Messages',
        type: 'standard',
        status: 'DRAFT',
        teamId: 'team-uuid',
        messages: [
          {
            type: 'INVITE',
            smsBody: 'You have been invited to complete an interview.',
            smsEnabled: true,
            emailSubject: 'Interview Invitation',
            emailHeader: "You've been invited!",
            emailBody: 'Please complete your interview.',
            emailEnabled: true
          }
        ]
      })
    });
    const messageGroup = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.post(
        'https://api.prod.qualifi.hr/qsi/gather/message-groups',
        headers={
            'x-api-key': api_key,
            'Content-Type': 'application/json'
        },
        json={
            'title': 'Standard Interview Messages',
            'type': 'standard',
            'status': 'DRAFT',
            'teamId': 'team-uuid',
            'messages': [
                {
                    'type': 'INVITE',
                    'smsBody': 'You have been invited to complete an interview.',
                    'smsEnabled': True,
                    'emailSubject': 'Interview Invitation',
                    'emailHeader': "You've been invited!",
                    'emailBody': 'Please complete your interview.',
                    'emailEnabled': True
                }
            ]
        }
    )
    messageGroup = response.json()
    ```
  </Tab>
</Tabs>

<CodeGroup>
  ```json Request theme={null}
  {
    "title": "Standard Interview Messages",
    "type": "standard",
    "status": "DRAFT",
    "teamId": "team-uuid",
    "default": false,
    "messages": [
      {
        "type": "INVITE",
        "smsBody": "You've been invited to complete an interview. Click here: {{link}}",
        "smsEnabled": true,
        "emailSubject": "Interview Invitation",
        "emailHeader": "You've been invited!",
        "emailBody": "Please complete your interview by clicking the link below.",
        "emailEnabled": true
      },
      {
        "type": "CANDIDATE_REMINDER",
        "smsBody": "Reminder: Complete your interview. Link: {{link}}",
        "smsEnabled": true,
        "emailSubject": "Interview Reminder",
        "emailHeader": "Don't forget!",
        "emailBody": "This is a reminder to complete your interview.",
        "emailEnabled": true
      },
      {
        "type": "COMPLETION_CONFIRMATION",
        "smsBody": "Thank you for completing your interview!",
        "smsEnabled": true,
        "emailSubject": "Interview Completed",
        "emailHeader": "Thank you!",
        "emailBody": "We've received your interview responses.",
        "emailEnabled": true
      }
    ]
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "messageGroup": {
        "id": "message-group-uuid",
        "title": "Standard Interview Messages",
        "status": "DRAFT",
        "type": "standard",
        "default": false,
        "organizationId": "org-uuid",
        "teamId": "team-uuid",
        "createdById": "user-uuid",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z",
        "archivedAt": null,
        "messages": [
          {
            "id": "message-uuid-1",
            "type": "INVITE",
            "smsBody": "You've been invited to complete an interview. Click here: {{link}}",
            "smsEnabled": true,
            "emailSubject": "Interview Invitation",
            "emailHeader": "You've been invited!",
            "emailBody": "Please complete your interview by clicking the link below.",
            "emailEnabled": true,
            "messageGroupId": "message-group-uuid",
            "createdAt": "2024-01-01T00:00:00Z",
            "updatedAt": "2024-01-01T00:00:00Z"
          }
        ]
      }
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## Update Message Group

Update an existing message group. You can update the title, status, type, team, or messages. If messages are not provided, existing messages are preserved.

**Endpoint:** `PATCH /qsi/gather/message-groups/{messageGroupId}`

<ParamField path="messageGroupId" type="string" required>
  UUID of the message group to update
</ParamField>

<ParamField name="title" type="string">
  Updated title
</ParamField>

<ParamField name="status" type="string">
  Updated status: `"DRAFT"` or `"PUBLISHED"`
</ParamField>

<ParamField name="messages" type="array">
  Updated array of messages (if provided, replaces existing messages)
</ParamField>

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X PATCH https://api.prod.qualifi.hr/qsi/gather/message-groups/{messageGroupId} \
      -H "x-api-key: ${API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "status": "PUBLISHED"
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch(
      `https://api.prod.qualifi.hr/qsi/gather/message-groups/${messageGroupId}`,
      {
        method: 'PATCH',
        headers: {
          'x-api-key': apiKey,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          status: 'PUBLISHED'
        })
      }
    );
    const messageGroup = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.patch(
        f'https://api.prod.qualifi.hr/qsi/gather/message-groups/{message_group_id}',
        headers={
            'x-api-key': api_key,
            'Content-Type': 'application/json'
        },
        json={
            'status': 'PUBLISHED'
        }
    )
    messageGroup = response.json()
    ```
  </Tab>
</Tabs>

<CodeGroup>
  ```json Request theme={null}
  {
    "title": "Updated Message Group Title",
    "status": "PUBLISHED",
    "messages": [
      {
        "id": "existing-message-uuid",
        "type": "INVITE",
        "smsBody": "Updated SMS body",
        "smsEnabled": true,
        "emailSubject": "Updated Email Subject",
        "emailHeader": "Updated Header",
        "emailBody": "Updated email body",
        "emailEnabled": true
      },
      {
        "type": "CANDIDATE_REMINDER",
        "smsBody": "New reminder message",
        "smsEnabled": true,
        "emailSubject": "Reminder",
        "emailHeader": "Reminder",
        "emailBody": "Don't forget to complete your interview.",
        "emailEnabled": true
      }
    ]
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "messageGroup": {
        "id": "message-group-uuid",
        "title": "Updated Message Group Title",
        "status": "PUBLISHED",
        "type": "standard",
        "default": false,
        "organizationId": "org-uuid",
        "teamId": "team-uuid",
        "createdById": "user-uuid",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:30:00Z",
        "archivedAt": null,
        "messages": [
          {
            "id": "message-uuid-1",
            "type": "INVITE",
            "smsBody": "Updated SMS body",
            "smsEnabled": true,
            "emailSubject": "Updated Email Subject",
            "emailHeader": "Updated Header",
            "emailBody": "Updated email body",
            "emailEnabled": true,
            "messageGroupId": "message-group-uuid",
            "createdAt": "2024-01-01T00:00:00Z",
            "updatedAt": "2024-01-01T00:30:00Z"
          }
        ]
      }
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:30:00Z"
    }
  }
  ```
</CodeGroup>

## Message Types

Available message types:

* **INVITE** - Initial interview invitation sent when a candidate interview is created
* **CANDIDATE\_REMINDER** - Reminder sent to candidates who haven't completed their interview
* **COMPLETION\_CONFIRMATION** - Confirmation message sent after interview completion

## Message Group Types

* **standard** - For standard audio interviews
* **questionnaire** - For questionnaire/text-based interviews

## Message Group Status

* **DRAFT** - Message group is not yet published and cannot be used
* **PUBLISHED** - Message group is active and can be used in interviews

## Message Variables

In SMS and email bodies, you can use the following variables:

* `{{link}}` - Interview invitation link (automatically replaced)

<Callout type="info">
  When updating messages, include the `id` field for existing messages you want
  to update. Messages without an `id` will be created as new messages. If you
  don't provide the `messages` array, existing messages will be preserved.
</Callout>

## Using Message Groups

When creating interviews, you can specify a `messageGroupId`:

```json theme={null}
{
  "title": "Software Engineer Interview",
  "questionIds": ["uuid1", "uuid2"],
  "messageGroupId": "uuid"
}
```

<Callout type="info">
  If no `messageGroupId` is specified, the default message group for your
  organization will be used.
</Callout>

## Related Resources

<CardGroup cols={2}>
  <Card title="Interviews" icon="file-text" href="/api-reference/interviews">
    Learn about creating interviews with message groups
  </Card>

  <Card title="Branding" icon="palette" href="/api-reference/branding">
    Learn about branding customization
  </Card>
</CardGroup>