> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.messageblue.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.messageblue.ai/_mcp/server.

# Send a text or attachment to a group chat

POST https://api.messageblue.ai/sendGroupMessage
Content-Type: application/json

Routes an outbound message to an existing group chat. Supports text and media attachments. If the group cannot be resolved directly, the agent falls back to resolving it from its participants. Set force=true to always use the participant resolution path.

Reference: https://docs.messageblue.ai/api-reference/messages/send-group

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: swagger
  version: 1.0.0
paths:
  /sendGroupMessage:
    post:
      operationId: sendGroup
      summary: Send a text or attachment to a group chat
      description: >-
        Routes an outbound message to an existing group chat. Supports text and
        media attachments. If the group cannot be resolved directly, the agent
        falls back to resolving it from its participants. Set force=true to
        always use the participant resolution path.
      tags:
        - messages
      parameters:
        - name: X-App-Id
          in: header
          description: >-
            Your MessageBlue App ID, sent in clear on every request. It is
            paired with request signing: each request is also signed with your
            App Secret (see the **Authentication** tag). The App Secret itself
            is NEVER transmitted — it is only the HMAC signing key.
          required: true
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Completed by agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized (HMAC)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            Duplicate content blocked. Codes:
            DUPLICATE_MESSAGE_SAME_NUMBER_DETECTED (per-contact, default 5
            minutes; clears on reply); AGENT_LEVEL_DUPLICATE_MESSAGE_BLOCKED
            (same agent across contacts, default 2 minutes);
            DUPLICATE_MESSAGE_BLOCKED (account/global, default 1 minute).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Consecutive-message warning blocked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: No agents available / agent offline
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: Agent timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendGroupMessageRequest'
servers:
  - url: https://api.messageblue.ai
    description: Production
  - url: http://localhost:8080
    description: Local development
components:
  schemas:
    SendGroupMessageRequest:
      type: object
      properties:
        from:
          type: string
          description: >-
            Optional: if not provided, it is resolved automatically. Cannot
            override an existing group mapping.
        groupId:
          type: string
          description: >-
            Group chat identifier. If it is invalid or stale, the agent resolves
            the chat from its participants.
        text:
          type: string
        attachments:
          type: array
          items:
            type: string
            format: uri
          description: Array of public URLs of attachments
        status_callback:
          type: string
          format: uri
          description: Optional status callback URL
        participants:
          type: array
          items:
            type: string
          description: >-
            Optional participant handles (E.164 phones or emails). Used to
            resolve the chat when the group identifier is missing or stale, and
            for the force flow.
        force:
          type: boolean
          description: >-
            If true, always resolve the chat from its participants before
            sending, instead of sending directly by group identifier.
      required:
        - groupId
      description: >-
        Either text or attachments must be provided. Supports participant/force
        fallback when groupId is stale or invalid.
      title: SendGroupMessageRequest
    MessageDispatchResult:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
        type:
          type: string
        from:
          type: string
        to:
          type: string
        groupId:
          type: string
        text:
          type: string
        attachments:
          type: array
          items:
            type: string
            format: uri
        messageGuid:
          type: string
        chatGuid:
          type: string
        outbound:
          type: boolean
        iMessageNumber:
          type: string
        idempotencyKey:
          type:
            - string
            - 'null'
          description: Echo of Idempotency-Key header, or null.
      title: MessageDispatchResult
    ResponseMeta:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        timestamp:
          type: string
          format: date-time
      required:
        - requestId
        - timestamp
      title: ResponseMeta
    SendResponse:
      type: object
      properties:
        ok:
          type: boolean
        data:
          $ref: '#/components/schemas/MessageDispatchResult'
          description: Endpoint-specific payload wrapped in a standard success envelope.
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      required:
        - ok
        - data
        - meta
      title: SendResponse
    FieldError:
      type: object
      properties:
        field:
          type: string
        issue:
          type: string
        message:
          type: string
      required:
        - field
        - issue
        - message
      title: FieldError
    ErrorResponseErrorDetails0:
      type: array
      items:
        $ref: '#/components/schemas/FieldError'
      title: ErrorResponseErrorDetails0
    ErrorResponseErrorDetails:
      oneOf:
        - $ref: '#/components/schemas/ErrorResponseErrorDetails0'
        - type: object
          additionalProperties:
            description: Any type
      description: Field validation errors (array) or domain-specific context (object).
      title: ErrorResponseErrorDetails
    ErrorResponseError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        requestId:
          type: string
          format: uuid
        details:
          $ref: '#/components/schemas/ErrorResponseErrorDetails'
          description: Field validation errors (array) or domain-specific context (object).
      required:
        - code
        - message
        - requestId
      title: ErrorResponseError
    ErrorResponse:
      type: object
      properties:
        ok:
          type: boolean
        error:
          $ref: '#/components/schemas/ErrorResponseError'
      required:
        - ok
        - error
      title: ErrorResponse
  securitySchemes:
    appId:
      type: apiKey
      in: header
      name: X-App-Id
      description: >-
        Your MessageBlue App ID, sent in clear on every request. It is paired
        with request signing: each request is also signed with your App Secret
        (see the **Authentication** tag). The App Secret itself is NEVER
        transmitted — it is only the HMAC signing key.

```

## Examples



**Request**

```json
{
  "groupId": "iMessage;+;chat789xyz"
}
```

**Response**

```json
{
  "ok": true,
  "data": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "status": "sent",
    "type": "result",
    "from": "+14155550123",
    "to": "group",
    "groupId": "iMessage;+;chat789xyz",
    "text": "Hello everyone, meeting starts at 3 PM.",
    "attachments": [
      "https://example.com/media/image1.jpg"
    ],
    "messageGuid": "A1B2C3D4E5F6G7H8I9J0",
    "chatGuid": "chat789xyz",
    "outbound": true,
    "iMessageNumber": "+14155550123",
    "idempotencyKey": "abc123xyz789"
  },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-07-10T06:00:00.000Z"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.messageblue.ai/sendGroupMessage"

payload = { "groupId": "iMessage;+;chat789xyz" }
headers = {
    "X-App-Id": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.messageblue.ai/sendGroupMessage';
const options = {
  method: 'POST',
  headers: {'X-App-Id': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"groupId":"iMessage;+;chat789xyz"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.messageblue.ai/sendGroupMessage"

	payload := strings.NewReader("{\n  \"groupId\": \"iMessage;+;chat789xyz\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-App-Id", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.messageblue.ai/sendGroupMessage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-App-Id"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"groupId\": \"iMessage;+;chat789xyz\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.messageblue.ai/sendGroupMessage")
  .header("X-App-Id", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"groupId\": \"iMessage;+;chat789xyz\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.messageblue.ai/sendGroupMessage', [
  'body' => '{
  "groupId": "iMessage;+;chat789xyz"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-App-Id' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.messageblue.ai/sendGroupMessage");
var request = new RestRequest(Method.POST);
request.AddHeader("X-App-Id", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"groupId\": \"iMessage;+;chat789xyz\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-App-Id": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = ["groupId": "iMessage;+;chat789xyz"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.messageblue.ai/sendGroupMessage")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```