Programmable Messenger

Sending Facebook Messenger and Instagram messages with Bird, and how the Human Agent messaging window works

Summary

Facebook Messenger and Instagram are asynchronous messaging channels that let businesses reply to people who message your Facebook Page or Instagram account. Both run on Meta's Messenger Platform and share the same messaging-window rules — including the Human Agent window described below. Everything on this page applies identically to Facebook Messenger and Instagram.

The messaging window

Meta only lets you message a contact within a limited window after their last message to you:

• Standard window — 24 hours. Normal replies must be sent within 24 hours of the contact's most recent message.

• Human Agent window — 7 days. A reply sent by a human agent may be delivered up to 7 days after the contact's last message. Meta calls this the HUMAN_AGENT tag.

Bird applies the HUMAN_AGENT tag for you, based on the message's use case — you never pass a Meta tag directly.

Sending via the Channels API

On the Channels API you set the use case with the meta.extraInformation.useCase field. Set it to conversation (or transactional) and Bird delivers the message as a Human Agent message (the 7-day window).

Send a message

post

Send a message to a channel

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

channelIdstring · uuidRequired

The ID for a channel

Body

application/json

and

anyOptional

object · ChannelMessageCreateWithTemplateOptional

or

object · ChannelMessageCreateWithBodyOptional

Responses

202

Message was accepted for processing

application/json

bodyone ofOptional

or

or

or

or

or

or

or

or

or

or

bodyIdstring · uuidOptional

channelIdstring · uuidRequired

chargeableUnitsinteger · uint32Optional

createdAtstring · date-timeRequired

detailsstringOptional

This field is used to store additional information related to the message status.

directionstring · enumOptionalPossible values:

idstring · uuidRequired

ignorePersistedEventhooksbooleanOptional

lastStatusAtstring · date-timeRequired

platformIdstringOptional

platformReferenceIdstringOptional

reasonstringOptional

referencestringOptional

A reference to the message. This can be used to identify the message in the channel.

scheduledForstring · date-timeOptional

Scheduled message send time (RFC3339). Messages scheduled within 10 minutes may be sent immediately; messages scheduled more than 35 days out will be rejected.

sendAtstring · date-timeOptional

statusstring · enumRequiredPossible values:

tagIdsstring · uuid[]Optional

tagsstring[]Optional

Tags to associate with the message. Tags are converted to lower case and automatically created if they don't exist. Up to 10 tags per message.

updatedAtstring · date-timeRequired

400

An error

application/json

404

An error

application/json

409

The request conflicts with the current state of the resource.

application/json

413

The request was rejected for exceeding a size limit: the total request body must not exceed 200 KB, and a single attachment's inline content must not exceed 100 KB.

application/json

422

The request contains invalid parameters or body fields.

application/json

post/workspaces/{workspaceId}/channels/{channelId}/messages

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/channels/{channelId}/messages HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2728

{
  "sender": {
    "connector": {
      "identifierValue": "[e-mail]",
      "annotations": {
        "name": "text"
      }
    }
  },
  "receiver": {
    "contacts": [
      {
        "id": "a1405560-c8d3-4b1a-877d-3f449ad95352",
        "identifierKey": "emailaddress",
        "identifierValue": "[e-mail]",
        "type": "cc",
        "identifiers": [
          {
            "identifierKey": "emailaddress",
            "identifierValue": "[e-mail]"
          }
        ],
        "platformAddress": "text",
        "platformAddressSelector": "text"
      }
    ]
  },
  "reference": "my-own-identifier",
  "template": {
    "name": "text",
    "projectId": "a1405560-c8d3-4b1a-877d-3f449ad95352",
    "version": "a1405560-c8d3-4b1a-877d-3f449ad95352",
    "locale": "text",
    "attachments": [
      {
        "mediaUrl": "https://example.com",
        "filename": "text",
        "inline": true
      }
    ],
    "shortLinks": {
      "enabled": true,
      "domain": "text"
    },
    "utmParameters": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "parameters": [
      {
        "type": "string",
        "key": "text",
        "value": "text"
      }
    ],
    "settings": {
      "disallowMmLite": true
    }
  },
  "meta": {
    "extraInformation": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "referral": {
      "source": "text",
      "title": "text",
      "text": "text",
      "group": "text",
      "metadata": {
        "source_id": "text",
        "source_url": "text",
        "media_url": "text",
        "tracking_id": "text"
      }
    },
    "order": {
      "products": [
        {
          "externalCatalogId": "text",
          "externalProductId": "text",
          "quantity": 1,
          "price": {
            "amount": 1,
            "exponent": 1,
            "currencyCode": "text"
          }
        }
      ]
    },
    "referredProduct": {
      "externalCatalogId": "text",
      "externalProductId": "text"
    },
    "email": {
      "subject": "text",
      "headers": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "from": {
        "username": "text",
        "displayName": "text"
      }
    },
    "sms": {
      "smartEncoding": true
    },
    "pushNotifications": {
      "gatewayTypeOverride": "apns"
    },
    "navigatorId": "123e4567-e89b-12d3-a456-426614174000",
    "navigatorMessageId": "123e4567-e89b-12d3-a456-426614174000",
    "flow": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "stepId": "text",
      "runId": "123e4567-e89b-12d3-a456-426614174000"
    },
    "journey": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "stepId": "text",
      "runId": "123e4567-e89b-12d3-a456-426614174000"
    },
    "campaign": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text"
    }
  },
  "replyTo": {
    "id": "text",
    "order": 1,
    "type": "message"
  },
  "body": {
    "type": "text",
    "text": {
      "text": "text",
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": true,
          "contentId": "text"
        }
      ],
      "actions": [
        {
          "type": "link",
          "link": {
            "text": "text",
            "url": "text"
          }
        }
      ],
      "metadata": {
        "subject": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "whatsapp": {
          "previewUrl": true
        },
        "line": {
          "emoji": {
            "items": [
              {
                "index": 1,
                "productId": "text",
                "emojiId": "text"
              }
            ]
          }
        },
        "telegram": {
          "parseMode": "Markdown"
        },
        "apple": {
          "summaryText": "text",
          "appClipPreview": true,
          "appClipRegion": "text"
        }
      }
    }
  },
  "notification": {
    "url": "text"
  },
  "capFrequency": true,
  "enableLinkTracking": true,
  "ignoreQuietHours": true,
  "ignoreGlobalHoldout": true,
  "tags": [
    "text"
  ],
  "shortLinks": {
    "domain": "text"
  },
  "scheduledFor": "2026-08-10T22:40:10.558Z",
  "validity": 1
}

{
  "body": {
    "text": {
      "actions": [
        {
          "link": {
            "metadata": {
              "description": {
                "label": "text"
              }
            },
            "text": "text",
            "url": "text"
          },
          "type": "link"
        }
      ],
      "attachments": [
        {
          "content": "text",
          "contentId": "text",
          "contentType": "text",
          "filename": "text",
          "inline": true,
          "mediaUrl": "text"
        }
      ],
      "metadata": {
        "apple": {
          "appClipPreview": true,
          "appClipRegion": "text",
          "summaryText": "text"
        },
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "line": {
          "emoji": {
            "items": [
              {
                "emojiId": "text",
                "index": 1,
                "length": 1,
                "productId": "text"
              }
            ]
          }
        },
        "paymentDetails": {
          "amount": "text",
          "currency": "text",
          "sessionIdentifier": "text",
          "state": "text"
        },
        "subject": "text",
        "telegram": {
          "parseMode": "text"
        },
        "whatsapp": {
          "callPermissionExpiration": "2026-08-10T22:40:10.558Z",
          "callPermissionResponse": "accept",
          "previewUrl": true
        }
      },
      "text": "text"
    },
    "type": "text"
  },
  "bodyId": "123e4567-e89b-12d3-a456-426614174000",
  "bodyStorage": {
    "type": "s3",
    "s3": {
      "bucketArn": "text",
      "encryptionKey": "text",
      "key": "text"
    }
  },
  "channelId": "123e4567-e89b-12d3-a456-426614174000",
  "chargeableUnits": 1,
  "context": {
    "id": "text",
    "tagIds": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "type": "text"
  },
  "createdAt": "2026-08-10T22:40:10.558Z",
  "details": "text",
  "direction": "incoming",
  "failure": {
    "code": 1,
    "description": "text",
    "source": {
      "code": "text",
      "name": "pre-processing"
    }
  },
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "ignorePersistedEventhooks": true,
  "lastStatusAt": "2026-08-10T22:40:10.558Z",
  "meta": {
    "campaign": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text"
    },
    "campaignId": "123e4567-e89b-12d3-a456-426614174000",
    "chargeOnceDelivered": true,
    "email": {
      "from": {
        "displayName": "text",
        "username": "text"
      },
      "headers": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "subject": "text"
    },
    "extraInformation": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "flow": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "runId": "123e4567-e89b-12d3-a456-426614174000",
      "scheduleExecutionId": "123e4567-e89b-12d3-a456-426614174000",
      "stepId": "text"
    },
    "formResponse": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "jsonResponse": "text",
      "requestIdentifier": "123e4567-e89b-12d3-a456-426614174000",
      "selections": [
        {
          "items": [
            {
              "identifier": "text",
              "title": "text",
              "type": "text",
              "value": "text"
            }
          ],
          "pageIdentifier": "text",
          "subtitle": "text",
          "title": "text"
        }
      ],
      "sessionIdentifier": "123e4567-e89b-12d3-a456-426614174000",
      "template": "text",
      "version": "text"
    },
    "ignoreGlobalHoldout": true,
    "ignoreQuietHours": true,
    "journey": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "runId": "123e4567-e89b-12d3-a456-426614174000",
      "scheduleExecutionId": "123e4567-e89b-12d3-a456-426614174000",
      "stepId": "text"
    },
    "longToShortLinks": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "metaThreadId": "text",
    "navigatorId": "123e4567-e89b-12d3-a456-426614174000",
    "navigatorMessageId": "123e4567-e89b-12d3-a456-426614174000",
    "order": {
      "products": [
        {
          "externalCatalogId": "text",
          "externalProductId": "text",
          "price": {
            "amount": 1,
            "currencyCode": "text",
            "exponent": 1
          },
          "quantity": 1
        }
      ]
    },
    "pushNotifications": {
      "gatewayTypeOverride": "firebase"
    },
    "referral": {
      "group": "text",
      "metadata": {
        "caption": "text",
        "mediaType": "text",
        "mediaUrl": "text",
        "sourceId": "text",
        "sourceUrl": "text",
        "timestamp": "2026-08-10T22:40:10.558Z",
        "trackingId": "text",
        "username": "text"
      },
      "source": "text",
      "text": "text",
      "title": "text"
    },
    "referredProduct": {
      "externalCatalogId": "text",
      "externalProductId": "text"
    },
    "renderedContentBlocks": [
      "text"
    ],
    "shortToLongLinks": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "skipThisMessage": "campaignHoldout",
    "sms": {
      "gatewayId": 1,
      "registeredDelivery": "final",
      "smartEncoding": true,
      "smpp": {
        "segments": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "registeredDelivery": "final"
          }
        ],
        "userId": "123e4567-e89b-12d3-a456-426614174000"
      },
      "validity": "2026-08-10T22:40:10.558Z"
    },
    "useFallback": true
  },
  "parts": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "order": 1,
      "platformReferenceId": "text",
      "platformStatusAt": "2026-08-10T22:40:10.558Z",
      "rawBody": "text",
      "reason": "text",
      "status": "accepted",
      "statusAt": "2026-08-10T22:40:10.558Z"
    }
  ],
  "platformId": "text",
  "platformReferenceId": "text",
  "previousMessages": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "useCaseType": "unspecified"
    }
  ],
  "reason": "text",
  "receiver": {
    "connector": {
      "annotations": {
        "name": "text"
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text",
      "types": [
        "text"
      ]
    },
    "contacts": [
      {
        "contactAnnotation": {
          "name": "text"
        },
        "countryCode": "text",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "identifierKey": "text",
        "identifierValue": "text",
        "identifiers": [
          {
            "identifierKey": "text",
            "identifierValue": "text"
          }
        ],
        "platformAddress": "text",
        "platformAddressSelector": "text",
        "receiverExpression": "text",
        "receiverValue": "text",
        "type": "text"
      }
    ],
    "device": {
      "gateway": "firebase",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text"
    },
    "inbox": {
      "emailRecipientType": "text",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierKey": "text",
      "identifierValue": "text",
      "type": "user"
    },
    "userContacts": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "identifierKey": "text",
        "identifierValue": "text",
        "type": "text"
      }
    ]
  },
  "reference": "text",
  "replyTo": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "order": 1,
    "platformReference": "text",
    "type": "message"
  },
  "schedule": {
    "reason": "text",
    "scheduledAt": "2026-08-10T22:40:10.558Z"
  },
  "scheduledFor": "2026-08-10T22:40:10.558Z",
  "sendAt": "2026-08-10T22:40:10.558Z",
  "sender": {
    "connector": {
      "annotations": {
        "name": "text"
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text",
      "types": [
        "text"
      ]
    },
    "contact": {
      "contactAnnotation": {
        "name": "text"
      },
      "countryCode": "text",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierKey": "text",
      "identifierValue": "text",
      "identifiers": [
        {
          "identifierKey": "text",
          "identifierValue": "text"
        }
      ],
      "platformAddress": "text",
      "platformAddressSelector": "text",
      "receiverExpression": "text",
      "receiverValue": "text",
      "type": "text"
    },
    "inbox": {
      "emailRecipientType": "text",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierKey": "text",
      "identifierValue": "text",
      "type": "user"
    },
    "userContact": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierKey": "text",
      "identifierValue": "text",
      "type": "text"
    }
  },
  "shortLinks": {
    "domain": "text"
  },
  "status": "accepted",
  "tagIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "tags": [
    "text"
  ],
  "template": {
    "attachments": [
      {
        "content": "text",
        "contentType": "text",
        "filename": "text",
        "inline": true,
        "mediaUrl": "text"
      }
    ],
    "deployment": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "locale": "text",
    "name": "text",
    "parameters": [
      {
        "key": "text",
        "sourceUrl": {
          "fullyReplaced": true,
          "value": "text"
        },
        "type": "string",
        "value": {}
      }
    ],
    "projectId": "123e4567-e89b-12d3-a456-426614174000",
    "settings": {
      "disallowMmLite": true
    },
    "shortLinks": {
      "domain": "text",
      "enabled": true
    },
    "templateBody": {
      "text": {
        "actions": [
          {
            "link": {
              "metadata": {
                "description": {
                  "label": "text"
                }
              },
              "text": "text",
              "url": "text"
            },
            "type": "link"
          }
        ],
        "attachments": [
          {
            "content": "text",
            "contentId": "text",
            "contentType": "text",
            "filename": "text",
            "inline": true,
            "mediaUrl": "text"
          }
        ],
        "metadata": {
          "apple": {
            "appClipPreview": true,
            "appClipRegion": "text",
            "summaryText": "text"
          },
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "line": {
            "emoji": {
              "items": [
                {
                  "emojiId": "text",
                  "index": 1,
                  "length": 1,
                  "productId": "text"
                }
              ]
            }
          },
          "paymentDetails": {
            "amount": "text",
            "currency": "text",
            "sessionIdentifier": "text",
            "state": "text"
          },
          "subject": "text",
          "telegram": {
            "parseMode": "text"
          },
          "whatsapp": {
            "callPermissionExpiration": "2026-08-10T22:40:10.558Z",
            "callPermissionResponse": "accept",
            "previewUrl": true
          }
        },
        "text": "text"
      },
      "type": "text"
    },
    "utmParameters": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "variables": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "version": "text"
  },
  "updatedAt": "2026-08-10T22:40:10.558Z"
}

Example Request Body

{
  "receiver": {
    "contacts": [
      {
        "identifierKey": "facebook",
        "identifierValue": "<the contact's PSID>"
      }
    ]
  },
  "body": {
    "type": "text",
    "text": {
      "text": "Thanks for reaching out — here's the update you asked for."
    }
  },
  "meta": {
    "extraInformation": {
      "useCase": "conversation"
    }
  }
}

The useCase value maps to Meta's messaging type as follows:

conversation or transactional	MESSAGE_TAG + HUMAN_AGENT	7 days (human agent)
marketing, otp, or omitted	UPDATE	24 hours (standard)

The Human Agent window is controlled by useCase only — not by which participant sends the message. To reply outside the 24-hour window, set useCase to conversation or transactional.

Sending via the Conversations API

Messages sent through the Conversations API are automatically classified with the conversation use case, so Messenger and Instagram messages are always delivered with the HUMAN_AGENT tag — you don't need to set anything.

Create message in conversation

post

Sends a message in a conversation. The message content can be comprised of either body or template. Attempting to send as a participant that hasn't been added to the conversation results in an error unless the option addMissingParticipants is set to true. Attempting to send messages in a closed conversation results in an error.

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

conversationIdstringRequired

The conversation ID

Example: 67e4d358-ca94-421e-98b7-448860df9d33

Body

application/json

or

Responses

201

OK

application/json

bodyone ofOptional

or

or

or

or

or

or

or

or

or

or

channelIdstring · uuidOptional

conversationCreatedAtstring · date-timeOptional

conversationIdstring · uuidRequired

createdAtstring · date-timeRequired

draftbooleanRequired

Whether this message is a draft.

idstring · uuidRequired

A unique identifier for this message.

reasonstringOptional

Failure reason. Populated when status is sending_failed or delivery_failed.

referencestringRequired

A customizable ID assigned to messages you send. Can be used to correlate messages with data from your own services. Must be globally unique within a workspace.

resourceUristringOptional

sourcestring · enumRequiredPossible values:

statusstring · enumRequiredPossible values:

typestring · enumOptionalPossible values:

updatedAtstring · date-timeRequired

403

The caller is not allowed to access the resource.

application/json

404

The requested resource was not found.

application/json

409

The request conflicts with the current state of the resource.

application/json

422

The request contains invalid parameters or body fields.

application/json

post/workspaces/{workspaceId}/conversations/{conversationId}/messages

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/conversations/{conversationId}/messages HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2414

{
  "draft": true,
  "reference": "my-own-business-logic-id-12345",
  "sender": {
    "name": "Bird Support",
    "email": "[e-mail]",
    "emailReplyToAddress": "[e-mail]"
  },
  "participantId": "85762b7e-1e25-4648-8e06-27195433cfe2",
  "replyToMessageId": "4fe755f0-3575-4a9e-b5d7-a184758af613",
  "participantType": "user",
  "participantContactIdentifierKey": "emailaddress",
  "participantContactIdentifierValue": "text",
  "recipients": [
    {
      "identifierKey": "emailaddress",
      "identifierValue": "[e-mail]",
      "platformAddressSelector": "attributes.workEmail",
      "type": "to"
    }
  ],
  "addMissingParticipants": true,
  "body": {
    "text": {
      "actions": [
        {
          "link": {
            "metadata": {
              "description": {
                "label": "text"
              }
            },
            "text": "text",
            "url": "text"
          },
          "type": "link"
        }
      ],
      "attachments": [
        {
          "content": "text",
          "contentId": "text",
          "contentType": "text",
          "filename": "text",
          "inline": true,
          "mediaUrl": "text"
        }
      ],
      "metadata": {
        "apple": {
          "appClipPreview": true,
          "appClipRegion": "text",
          "summaryText": "text"
        },
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "line": {
          "emoji": {
            "items": [
              {
                "emojiId": "text",
                "index": 1,
                "length": 1,
                "productId": "text"
              }
            ]
          }
        },
        "paymentDetails": {
          "amount": "text",
          "currency": "text",
          "sessionIdentifier": "text",
          "state": "text"
        },
        "subject": "text",
        "telegram": {
          "parseMode": "text"
        },
        "whatsapp": {
          "callPermissionExpiration": "2026-08-10T22:40:10.558Z",
          "callPermissionResponse": "accept",
          "previewUrl": true
        }
      },
      "text": "text"
    },
    "type": "text"
  },
  "replyTo": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "order": 1,
    "platformReference": "text",
    "type": "message"
  },
  "appendPreviousMessage": true,
  "channelId": "38038a15-0dde-4114-a882-df4a0e8c98e8",
  "participants": [
    {
      "id": "986c5b08-3ec7-424a-a380-f3b41dc02746",
      "type": "user"
    }
  ],
  "name": "Re: Your refund request",
  "description": "Refund request ticket",
  "visibility": "public",
  "accessibility": "open",
  "attributes": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "meta": {
    "email": {
      "subject": "text",
      "headers": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "from": {
        "username": "john.doe",
        "displayName": "John Doe"
      }
    },
    "extraInformation": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "referral": {
      "source": "text",
      "title": "text",
      "text": "text",
      "group": "text",
      "metadata": {
        "sourceId": "120211000000000000",
        "sourceUrl": "https://instagram.com/p/EXAMPLEID",
        "mediaType": "IMAGE",
        "mediaUrl": "https://cdninstagram.com/v/example",
        "caption": "Introducing Dream Summer Days Daily SPF, your go-to sunscreen for safeguarding your skin's glow under the sun's embrace.",
        "username": "DreamCosmetics",
        "timestamp": "2024-11-28T12:00:00.000Z",
        "trackingId": "text"
      }
    }
  }
}

{
  "body": {
    "text": {
      "actions": [
        {
          "link": {
            "metadata": {
              "description": {
                "label": "text"
              }
            },
            "text": "text",
            "url": "text"
          },
          "type": "link"
        }
      ],
      "attachments": [
        {
          "content": "text",
          "contentId": "text",
          "contentType": "text",
          "filename": "text",
          "inline": true,
          "mediaUrl": "text"
        }
      ],
      "metadata": {
        "apple": {
          "appClipPreview": true,
          "appClipRegion": "text",
          "summaryText": "text"
        },
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "line": {
          "emoji": {
            "items": [
              {
                "emojiId": "text",
                "index": 1,
                "length": 1,
                "productId": "text"
              }
            ]
          }
        },
        "paymentDetails": {
          "amount": "text",
          "currency": "text",
          "sessionIdentifier": "text",
          "state": "text"
        },
        "subject": "text",
        "telegram": {
          "parseMode": "text"
        },
        "whatsapp": {
          "callPermissionExpiration": "2026-08-10T22:40:10.558Z",
          "callPermissionResponse": "accept",
          "previewUrl": true
        }
      },
      "text": "text"
    },
    "type": "text"
  },
  "channelId": "123e4567-e89b-12d3-a456-426614174000",
  "conversationCreatedAt": "2026-08-10T22:40:10.558Z",
  "conversationId": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2026-08-10T22:40:10.558Z",
  "draft": true,
  "draftMeta": {
    "creatorType": "user"
  },
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "interactions": [
    {
      "bodyTemplateProjectId": "123e4567-e89b-12d3-a456-426614174000",
      "channelId": "123e4567-e89b-12d3-a456-426614174000",
      "context": {
        "id": "text",
        "tagIds": [
          "123e4567-e89b-12d3-a456-426614174000"
        ],
        "type": "text"
      },
      "createdAt": "2026-08-10T22:40:10.558Z",
      "details": "text",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "isFirstInteraction": true,
      "isFirstInteractionIncludingBots": true,
      "journey": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "runId": "123e4567-e89b-12d3-a456-426614174000",
        "scheduleExecutionId": "123e4567-e89b-12d3-a456-426614174000",
        "stepId": "text"
      },
      "messageCreatedAt": "2026-08-10T22:40:10.558Z",
      "messageId": "123e4567-e89b-12d3-a456-426614174000",
      "messagePartsCount": 1,
      "messageReference": "text",
      "messageTags": [
        "text"
      ],
      "metadata": {
        "button": {
          "payload": "text"
        },
        "conversion": {
          "method": "unknown",
          "status": "converted",
          "timestamp": "2026-08-10T22:40:10.558Z",
          "type": "otp"
        },
        "extraInformation": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "link": {
          "clickType": "link",
          "name": "text",
          "url": "text"
        },
        "prefetched": true,
        "reaction": {
          "action": "react",
          "emoji": "text"
        },
        "renderedContentBlocks": [
          "text"
        ],
        "subscriptionList": {
          "subscriptionListId": "123e4567-e89b-12d3-a456-426614174000"
        }
      },
      "notification": {
        "template": "text",
        "url": "text"
      },
      "platformId": "text",
      "platformReferenceId": "text",
      "receiver": {
        "connector": {
          "annotations": {
            "name": "text"
          },
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierValue": "text",
          "types": [
            "text"
          ]
        },
        "contacts": [
          {
            "contactAnnotation": {
              "name": "text"
            },
            "countryCode": "text",
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "identifierKey": "text",
            "identifierValue": "text",
            "identifiers": [
              {
                "identifierKey": "text",
                "identifierValue": "text"
              }
            ],
            "platformAddress": "text",
            "platformAddressSelector": "text",
            "receiverExpression": "text",
            "receiverValue": "text",
            "type": "text"
          }
        ],
        "device": {
          "gateway": "firebase",
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierValue": "text"
        },
        "inbox": {
          "emailRecipientType": "text",
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierKey": "text",
          "identifierValue": "text",
          "type": "user"
        },
        "userContacts": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "identifierKey": "text",
            "identifierValue": "text",
            "type": "text"
          }
        ]
      },
      "type": "invalid",
      "useCaseType": "unspecified"
    }
  ],
  "meta": {
    "campaign": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text"
    },
    "campaignId": "123e4567-e89b-12d3-a456-426614174000",
    "chargeOnceDelivered": true,
    "email": {
      "from": {
        "displayName": "text",
        "username": "text"
      },
      "headers": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "subject": "text"
    },
    "extraInformation": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "flow": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "runId": "123e4567-e89b-12d3-a456-426614174000",
      "scheduleExecutionId": "123e4567-e89b-12d3-a456-426614174000",
      "stepId": "text"
    },
    "formResponse": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "jsonResponse": "text",
      "requestIdentifier": "123e4567-e89b-12d3-a456-426614174000",
      "selections": [
        {
          "items": [
            {
              "identifier": "text",
              "title": "text",
              "type": "text",
              "value": "text"
            }
          ],
          "pageIdentifier": "text",
          "subtitle": "text",
          "title": "text"
        }
      ],
      "sessionIdentifier": "123e4567-e89b-12d3-a456-426614174000",
      "template": "text",
      "version": "text"
    },
    "ignoreGlobalHoldout": true,
    "ignoreQuietHours": true,
    "journey": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "runId": "123e4567-e89b-12d3-a456-426614174000",
      "scheduleExecutionId": "123e4567-e89b-12d3-a456-426614174000",
      "stepId": "text"
    },
    "longToShortLinks": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "metaThreadId": "text",
    "navigatorId": "123e4567-e89b-12d3-a456-426614174000",
    "navigatorMessageId": "123e4567-e89b-12d3-a456-426614174000",
    "order": {
      "products": [
        {
          "externalCatalogId": "text",
          "externalProductId": "text",
          "price": {
            "amount": 1,
            "currencyCode": "text",
            "exponent": 1
          },
          "quantity": 1
        }
      ]
    },
    "pushNotifications": {
      "gatewayTypeOverride": "firebase"
    },
    "referral": {
      "group": "text",
      "metadata": {
        "caption": "text",
        "mediaType": "text",
        "mediaUrl": "text",
        "sourceId": "text",
        "sourceUrl": "text",
        "timestamp": "2026-08-10T22:40:10.558Z",
        "trackingId": "text",
        "username": "text"
      },
      "source": "text",
      "text": "text",
      "title": "text"
    },
    "referredProduct": {
      "externalCatalogId": "text",
      "externalProductId": "text"
    },
    "renderedContentBlocks": [
      "text"
    ],
    "shortToLongLinks": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "skipThisMessage": "campaignHoldout",
    "sms": {
      "gatewayId": 1,
      "registeredDelivery": "final",
      "smartEncoding": true,
      "smpp": {
        "segments": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "registeredDelivery": "final"
          }
        ],
        "userId": "123e4567-e89b-12d3-a456-426614174000"
      },
      "validity": "2026-08-10T22:40:10.558Z"
    },
    "useFallback": true
  },
  "reason": "text",
  "receiver": {
    "connector": {
      "annotations": {
        "name": "text"
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text",
      "types": [
        "text"
      ]
    },
    "contacts": [
      {
        "contactAnnotation": {
          "name": "text"
        },
        "countryCode": "text",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "identifierKey": "text",
        "identifierValue": "text",
        "identifiers": [
          {
            "identifierKey": "text",
            "identifierValue": "text"
          }
        ],
        "platformAddress": "text",
        "platformAddressSelector": "text",
        "receiverExpression": "text",
        "receiverValue": "text",
        "type": "text"
      }
    ],
    "device": {
      "gateway": "firebase",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text"
    },
    "inbox": {
      "emailRecipientType": "text",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierKey": "text",
      "identifierValue": "text",
      "type": "user"
    },
    "userContacts": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "identifierKey": "text",
        "identifierValue": "text",
        "type": "text"
      }
    ]
  },
  "receiverTypes": [
    "to"
  ],
  "recipients": [
    {
      "contactAnnotation": {
        "name": "text"
      },
      "countryCode": "text",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierKey": "text",
      "identifierValue": "text",
      "identifiers": [
        {
          "identifierKey": "text",
          "identifierValue": "text"
        }
      ],
      "platformAddress": "text",
      "platformAddressSelector": "text",
      "receiverExpression": "text",
      "receiverValue": "text",
      "type": "text"
    }
  ],
  "reference": "text",
  "replyTo": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "order": 1,
    "platformReference": "text",
    "type": "message"
  },
  "resourceUri": "text",
  "sender": {
    "email": "text",
    "name": "text",
    "avatarUrl": "text",
    "contact": {
      "identifierKey": "text",
      "identifierValue": "text",
      "platformAddress": "text",
      "platformAddressSelector": "text"
    },
    "conversationId": "123e4567-e89b-12d3-a456-426614174000",
    "createdAt": "2026-08-10T22:40:10.558Z",
    "displayName": "text",
    "id": "text",
    "resourceUri": "text",
    "status": "invited",
    "type": "user",
    "updatedAt": "2026-08-10T22:40:10.558Z"
  },
  "source": "conversations",
  "status": "accepted",
  "template": {
    "attachments": [
      {
        "content": "text",
        "contentType": "text",
        "filename": "text",
        "inline": true,
        "mediaUrl": "text"
      }
    ],
    "deployment": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "locale": "text",
    "name": "text",
    "parameters": [
      {
        "key": "text",
        "sourceUrl": {
          "fullyReplaced": true,
          "value": "text"
        },
        "type": "string",
        "value": {}
      }
    ],
    "projectId": "123e4567-e89b-12d3-a456-426614174000",
    "settings": {
      "disallowMmLite": true
    },
    "shortLinks": {
      "domain": "text",
      "enabled": true
    },
    "templateBody": {
      "text": {
        "actions": [
          {
            "link": {
              "metadata": {
                "description": {
                  "label": "text"
                }
              },
              "text": "text",
              "url": "text"
            },
            "type": "link"
          }
        ],
        "attachments": [
          {
            "content": "text",
            "contentId": "text",
            "contentType": "text",
            "filename": "text",
            "inline": true,
            "mediaUrl": "text"
          }
        ],
        "metadata": {
          "apple": {
            "appClipPreview": true,
            "appClipRegion": "text",
            "summaryText": "text"
          },
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "line": {
            "emoji": {
              "items": [
                {
                  "emojiId": "text",
                  "index": 1,
                  "length": 1,
                  "productId": "text"
                }
              ]
            }
          },
          "paymentDetails": {
            "amount": "text",
            "currency": "text",
            "sessionIdentifier": "text",
            "state": "text"
          },
          "subject": "text",
          "telegram": {
            "parseMode": "text"
          },
          "whatsapp": {
            "callPermissionExpiration": "2026-08-10T22:40:10.558Z",
            "callPermissionResponse": "accept",
            "previewUrl": true
          }
        },
        "text": "text"
      },
      "type": "text"
    },
    "utmParameters": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "variables": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "version": "text"
  },
  "type": "text",
  "updatedAt": "2026-08-10T22:40:10.558Z"
}

Example Request Body

{
  "participantType": "accessKey",
  "participantId": "<access key ID>",
  "body": {
    "type": "text",
    "text": {
      "text": "Thanks for reaching out — here's the update you asked for."
    }
  }
}

Any useCase you set in meta.extraInformation on the Conversations API is overridden with conversation, so the Human Agent window always applies.