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

# v2.8.0 - Group Messaging & Synchronous Operations

> Adds group_message resource support, group message webhook events, and synchronous write operations across telematics endpoints

**Released 4th May 2026**

This minor release introduces the `group_message` resource type across integrations and notifications APIs, new webhook events for group message lifecycle tracking, and a new `is_sync` query parameter for synchronous write operations on telematics resources.

<Check>
  **Minor Release:** All changes are backward-compatible additions. No breaking changes to existing integrations.
</Check>

## Group Messaging Resource Support

### New Resource Type

<AccordionGroup>
  <Accordion title="group_message Resource" icon="messages">
    **Added to `ResourceEnum`:**

    * `group_message` — Enables group messaging data to be used as a resource type across the integrations API

    This new value is now accepted and returned across all resource-related fields in the integrations API, including schedules, executions, resource operations, and data freshness endpoints.
  </Accordion>
</AccordionGroup>

### Affected Integrations Endpoints

The following endpoints now accept and return `group_message` as a valid `resource` value:

<AccordionGroup>
  <Accordion title="Resource Operations" icon="list">
    * `GET /v2/integrations/connections/resource-operations` — `resource` filter now accepts `group_message`; `resource` field in response now includes `group_message`
    * `GET /v2/integrations/connections/{connection_id}/resource-operations/{resource_operation_id}` — `resource` field in response now includes `group_message`
  </Accordion>

  <Accordion title="Data Freshness" icon="clock">
    * `GET /v2/integrations/connections/data-freshness` — `resource` field in response now includes `group_message`
  </Accordion>
</AccordionGroup>

### Example Usage

Create a schedule for group messaging data ingestion:

```bash theme={null}
POST /v2/integrations/connections/{connection_id}/schedules
Content-Type: application/json

{
  "resource": "group_message",
  "cron": "0 * * * *"
}
```

Filter resource operations by the new resource type:

```bash theme={null}
GET /v2/integrations/connections/resource-operations?resource=group_message
```

***

## Group Message Webhook Events

### New Webhook Events

<AccordionGroup>
  <Accordion title="Group Message Lifecycle Events" icon="bell">
    **Added:**

    * `group_message.added` — Emitted when a new group message is added to the database (i.e. the record fetched from the TSP is new and generated a new record)
    * `group_message.modified` — Emitted when a group message is updated in the database (i.e. the record fetched from the TSP differs from what was stored and prompted an update)
    * `group_message.*` — Wildcard subscription for all group message events

    **Example payload:**

    ```json theme={null}
    {
      "event_name": "group_message.added",
      "version": "2.8",
      "data": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "fleet_id": "123e4567-e89b-12d3-a456-426614174000"
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

### Subscribing to Group Message Events

<Steps>
  <Step title="Subscribe to group message events">
    Update your webhook subscriptions to include group message events:

    ```bash theme={null}
    POST /v2/notifications/webhooks
    Content-Type: application/json

    {
      "url": "https://your-domain.com/webhooks",
      "event_name": "group_message.added"
    }
    ```

    Or use the wildcard subscription to capture all group message events:

    ```bash theme={null}
    POST /v2/notifications/webhooks
    Content-Type: application/json

    {
      "url": "https://your-domain.com/webhooks",
      "event_name": "group_message.*"
    }
    ```
  </Step>

  <Step title="Handle group message webhook events">
    Process incoming group message events in your webhook handler:

    ```javascript theme={null}
    app.post('/webhooks', (req, res) => {
      const { event_name, data } = req.body;

      switch (event_name) {
        case 'group_message.added':
          // A new group message was ingested from the TSP
          console.log('New group message:', data[0].id);
          break;

        case 'group_message.modified':
          // An existing group message was updated
          console.log('Updated group message:', data[0].id);
          break;
      }

      res.status(200).send('OK');
    });
    ```
  </Step>

  <Step title="Filter webhooks by event name">
    Use the `event_name` query parameter on `GET /v2/notifications/webhooks` to list only group message webhook subscriptions:

    ```bash theme={null}
    GET /v2/notifications/webhooks?event_name=group_message.added
    ```
  </Step>
</Steps>

***

## Synchronous Write Operations

### New `is_sync` Query Parameter

A new `is_sync` boolean query parameter is now available on all telematics write endpoints (create and update). This allows you to choose between synchronous and asynchronous processing for resource operations.

<AccordionGroup>
  <Accordion title="is_sync Parameter Details" icon="bolt">
    | Property | Value |
    | - | - |
    | **Parameter name** | `is_sync` |
    | **Location** | Query string |
    | **Type** | `boolean` |
    | **Default** | `false` |
    | **Required** | No |

    **Behavior:**

    * **`is_sync=false` (default):** Catena creates an asynchronous operation and returns an operation ID. You can poll the operation status to track completion.
    * **`is_sync=true`:** Catena attempts to create or update the resource immediately with the TSP and returns the result in the response. You are responsible for handling any necessary retries in case of transient failures.
  </Accordion>
</AccordionGroup>

<Warning>
  When using `is_sync=true`, you are responsible for implementing retry logic for transient failures. Synchronous operations may return `502` if the TSP is temporarily unavailable.
</Warning>

### Affected Endpoints

<AccordionGroup>
  <Accordion title="Fleet Operations & Tracking" icon="truck">
    * `POST /v2/telematics/vehicles` — Create Vehicle
    * `PATCH /v2/telematics/vehicles/{id}` — Update Vehicle
    * `POST /v2/telematics/trailers` — Create Trailer
    * `PATCH /v2/telematics/trailers/{id}` — Update Trailer
  </Accordion>

  <Accordion title="Drivers & Users" icon="users">
    * `POST /v2/telematics/users` — Create User
    * `PATCH /v2/telematics/users/{id}` — Update User
    * `POST /v2/telematics/messages` — Create Message
    * `POST /v2/telematics/group-messages` — Create Group Message
  </Accordion>

  <Accordion title="Compliance & Maintenance" icon="clipboard-check">
    * `POST /v2/telematics/dvir-logs` — Create DVIR Log
    * `POST /v2/telematics/fuel-transactions` — Create Fuel Transaction
  </Accordion>
</AccordionGroup>

### Example Usage

Create a vehicle synchronously:

```bash theme={null}
POST /v2/telematics/vehicles?is_sync=true
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "vehicle_name": "Truck-42",
  "vin": "1HGCM82633A123456"
}
```

Create a vehicle asynchronously (default behavior):

```bash theme={null}
POST /v2/telematics/vehicles
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "vehicle_name": "Truck-42",
  "vin": "1HGCM82633A123456"
}
```

***

## Migration Checklist

<Steps>
  <Step title="No action required for existing integrations">
    All changes are purely additive. Existing schedules, webhooks, filters, and write operations continue to work without modification.
  </Step>

  <Step title="Opt in to group_message data">
    If your integration needs to ingest group messaging data, create a new schedule using `"resource": "group_message"` on the relevant connection.
  </Step>

  <Step title="Subscribe to group message webhook events">
    If you want to track group message lifecycle changes, create webhook subscriptions for `group_message.added`, `group_message.modified`, or `group_message.*`.
  </Step>

  <Step title="Opt in to synchronous operations">
    If you need immediate confirmation of resource creation or updates, add `?is_sync=true` to your write requests. Remember to implement retry logic for transient failures.
  </Step>
</Steps>

***

## Need Help?

<CardGroup cols={2}>
  <Card title="Integrations API Reference" icon="puzzle-piece" href="/api-reference/integrations-api">
    View complete endpoint documentation for the Integrations API
  </Card>

  <Card title="Notifications API Reference" icon="bell" href="/api-reference/notifications-api">
    View complete endpoint documentation for the Notifications API
  </Card>

  <Card title="Telematics API Reference" icon="satellite-dish" href="/api-reference/telematics-api">
    View complete endpoint documentation for the Telematics API
  </Card>

  <Card title="Contact Support" icon="life-ring" href="mailto:support@catenaclearing.io">
    Questions about these changes? Our team is here to help
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.