Sending WhatsApp messages

In order to send a WhatsApp message, you must have an active WhatsApp channel and perform a HTTP request to the following endpoint with a valid access key

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

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-06-16T23:52:00.518Z",
  "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-06-16T23:52:00.518Z",
          "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-06-16T23:52:00.518Z",
  "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-06-16T23:52:00.518Z",
  "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-06-16T23:52:00.518Z",
        "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-06-16T23:52:00.518Z"
    },
    "useFallback": true
  },
  "parts": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "order": 1,
      "platformReferenceId": "text",
      "platformStatusAt": "2026-06-16T23:52:00.518Z",
      "rawBody": "text",
      "reason": "text",
      "status": "accepted",
      "statusAt": "2026-06-16T23:52:00.518Z"
    }
  ],
  "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-06-16T23:52:00.518Z"
  },
  "scheduledFor": "2026-06-16T23:52:00.518Z",
  "sendAt": "2026-06-16T23:52:00.518Z",
  "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-06-16T23:52:00.518Z",
            "callPermissionResponse": "accept",
            "previewUrl": true
          }
        },
        "text": "text"
      },
      "type": "text"
    },
    "utmParameters": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "variables": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "version": "text"
  },
  "updatedAt": "2026-06-16T23:52:00.518Z"
}

When sending outbound messages as well as setting the receiver information you must set message body field in all cases except for sending a message template when you must only set the template field

Body

{
 "receiver": {
   "contacts": [
     {
       "identifierKey": "phonenumber",
       "identifierValue": "[phone]"
     }
   ]
 },
 "body": {...}
}

Template

{
 "receiver": {
   "contacts": [
     {
       "identifierKey": "phonenumber",
       "identifierValue": "[phone]"
     }
   ]
 },
 "template": {...}
}

If it has been more than 24 hours since a customer last messaged you, you have to start a conversation by sending a template message first. Non-template messages can only be sent when the customer care window is active. You can check the expiry time for an active customer care window for a contact by making a request as follows:

Get channel details for a contact

get

Retrieve channel information for a given contact.

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

contactIdstring · uuidRequired

The ID for a contact

Query parameters

contactIdentifierValuestringOptional

The receiver identifier value.

Responses

200

OK

application/json

404

An error

application/json

get

/workspaces/{workspaceId}/channels/{channelId}/contacts/{contactId}

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/channels/{channelId}/contacts/{contactId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "serviceWindowExpireAt": "2026-06-16T23:52:00.518Z",
  "isPermanentSession": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

The Channels API supports many of the features of WhatsApp, however due to the omni channel nature of the API there may be some differences between the Channels API message and the native WhatsApp API. Here is an overview of the WhatsApp messages types and Channels API message types:

WhatsApp API type	Channels API
text	text
image / sticker	image
audio / document / video	file
location	location
reaction	-
interactive - quick reply button	text + action / image + action
interactive - list	list
interactive - carousel	carousel
interactive - multi product message	-
interactive - product	-
contacts	-
replies	replyTo
template	template

Outbound messages

Except for the template section all examples below must be set in the body field.

{
 "receiver": {
   "contacts": [
     {
       "identifierValue": "[phone]"
     }
   ]
 },
 "body": {...}
}

Text

Text Message

{ "type": "text", "text": { "text": "Single text message" } }

Text message with reply buttons

{ "type": "text", "text": { "text": "Single text message with reply actions", "actions": [ { "type": "reply", "reply": { "text": "Reply action 1" } }, { "type": "reply", "reply": { "text": "Reply action 2" } } ] } }

Text message with postback actions

{ "type": "text", "text": { "text": "Single text message with postback actions", "actions": [ { "type": "postback", "postback": { "text": "Postback action 1", "payload": "postback-payload-1" } }, { "type": "postback", "postback": { "text": "Postback action 2", "payload": "postback-payload-2" } } ] } }

Text message with reply and postback actions

{ "type": "text", "text": { "text": "Single text message with reply and postback actions", "actions": [ { "type": "postback", "postback": { "text": "Postback action 1", "payload": "postback-payload-1" } }, { "type": "reply", "reply": { "text": "Reply action 1" } } ] } }

Text message with location request

{ "text": "Single text message with location request", "actions": [ { "type": "locationRequest" } ] }

Image

Single image message

{ "type": "image", "image": { "images": [ { "altText": "Label of first image", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FRPPgQAGyZE7rvIh3WM2Z%2Fimage2.avif?alt=media" } ] } }

Single image message with text

{ "type": "image", "image": { "images": [ { "altText": "Label of first image", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FRPPgQAGyZE7rvIh3WM2Z%2Fimage2.avif?alt=media" } ], "text": "Single image message" } }

Multiple image message

{ "type": "image", "image": { "images": [ { "altText": "Label of first image", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FrEM9zztd8SEiJS6RQuR3%2Fimage.png?alt=media" }, { "altText": "Label of second image", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FRPPgQAGyZE7rvIh3WM2Z%2Fimage2.avif?alt=media" } ], "text": "Multiple images message" } }

Single image message with postback actions

{"type": "image", "image": { "images": [ { "altText": "Image label", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FrEM9zztd8SEiJS6RQuR3%2Fimage.png?alt=media" } ], "text": "Single image message with postback actions", "actions": [ { "type": "postback", "postback": { "payload": "postback-payload-1", "text": "Postback option 1" } }, { "postback": { "payload": "postback-payload-2", "text": "Postback option 2" }, "type": "postback" } ] } }

Single image message with label and reply actions

{ "type": "image", "image": { "text": "Single image message with reply actions", "images": [ { "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FrEM9zztd8SEiJS6RQuR3%2Fimage.png?alt=media", "altText": "Image label" } ], "actions": [ { "type": "reply", "reply": { "text": "Reply action 1" } }, { "type": "reply", "reply": { "text": "Reply action 2" } } ] } }

Single image message with label, postback and reply actions

{ "type": "image", "image": { "text": "Single image message with postback and reply actions", "images": [ { "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FrEM9zztd8SEiJS6RQuR3%2Fimage.png?alt=media", "altText": "Image label" } ], "actions": [ { "type": "postback", "postback": { "text": "Postback action", "payload": "postback-payload" } }, { "type": "reply", "reply": { "text": "Reply action" } } ] } }

Multiple images message with labels and postback actions

{ "type": "image", "image": { "images": [ { "altText": "First image label", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FrEM9zztd8SEiJS6RQuR3%2Fimage.png?alt=media" }, { "altText": "Second image label", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FRPPgQAGyZE7rvIh3WM2Z%2Fimage2.avif?alt=media" } ], "text": "Multiple images message with postback actions", "actions": [ { "type": "postback", "postback": { "payload": "postback-payload-1", "text": "Postback action 1" } }, { "postback": { "payload": "postback-payload-2", "text": "Postback action 2" }, "type": "postback" } ] } }

Multiple images message with reply actions

{ "type": "image", "image": { "images": [ { "altText": "First image label", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FrEM9zztd8SEiJS6RQuR3%2Fimage.png?alt=media" }, { "altText": "Second image label", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FRPPgQAGyZE7rvIh3WM2Z%2Fimage2.avif?alt=media" } ], "text": "Multiple images message with reply actions", "actions": [ { "type": "reply", "reply": { "text": "Reply action 1" } }, { "reply": { "text": "Reply action 2" }, "type": "reply" } ] } }

Multiple images message with labels, postback and reply actions

{ "type": "image", "image": { "images": [ { "altText": "First image label", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FrEM9zztd8SEiJS6RQuR3%2Fimage.png?alt=media" }, { "altText": "Second image label", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FRPPgQAGyZE7rvIh3WM2Z%2Fimage2.avif?alt=media" } ], "text": "Multiple images message with postback and reply actions", "actions": [ { "type": "postback", "postback": { "payload": "postback-payload", "text": "Postback action" } }, { "reply": { "text": "Reply action" }, "type": "reply" } ] } }

File

Single file message

{ "type": "file", "file": { "text": "Single file message", "files": [ { "contentType": "video/mp4", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FtXMQ4lIinia9ehf4EpC4%2Fvideo.mp4?alt=media" } ] } }

Single file message with postback and reply actions

{ "type": "file", "file": { "text": "Single file message", "files": [ { "contentType": "video/mp4", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FtXMQ4lIinia9ehf4EpC4%2Fvideo.mp4?alt=media" } ], "actions": [ { "type": "postback", "postback": { "text": "Postback action" } }, { "type": "reply", "reply": { "text": "Reply action" } } ] } }

Multiple files message

{ "type": "file", "file": { "text": "Multiple files message", "files": [ { "contentType": "video/mp4", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FtXMQ4lIinia9ehf4EpC4%2Fvideo.mp4?alt=media" }, { "contentType": "application/pdf", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FPnRToYX2feW96HAOrh4x%2Fdocument.pdf?alt=media" } ] } }

Multiple files message with filename

{ "type": "file", "file": { "text": "Multiple files message", "files": [ { "contentType": "video/mp4", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FtXMQ4lIinia9ehf4EpC4%2Fvideo.mp4?alt=media" }, { "contentType": "application/pdf", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FPnRToYX2feW96HAOrh4x%2Fdocument.pdf?alt=media", "filename": "passport.pdf" } ] } }

Multiple files message with two postback actions and a reply action

{ "type": "file", "file": { "text": "Multiple files message", "files": [ { "contentType": "video/mp4", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FtXMQ4lIinia9ehf4EpC4%2Fvideo.mp4?alt=media" }, { "contentType": "application/pdf", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FPnRToYX2feW96HAOrh4x%2Fdocument.pdf?alt=media", "filename": "passport.pdf" } ], "actions": [ { "type": "postback", "postback": { "text": "Postback action 1", "payload": "postback-payload-1" } }, { "type": "postback", "postback": { "text": "Postback action 2", "payload": "postback-payload-2" } }, { "type": "reply", "reply": { "text": "Reply action" } } ] } }

Location

{ "type": "location", "location": { "coordinates": { "latitude": 52.3435942, "longitude": 4.9091077 }, "location": { "address": "Trompenburgstraat 2C, 1079 TX Amsterdam", "label": "MessageBird Amsterdam office" } } }

List

List message without sections

{ "type": "list", "list": { "items": [ { "actions": [ { "type": "postback", "postback": { "payload": "postback-action-payload-1", "text": "Postback action 1" } }, { "type": "postback", "postback": { "payload": "postback-action-payload-2", "text": "Postback action 2" } } ] } ], "title": "List title", "altText": "List alt text", "text": "List text" } }

List message with sections

{ "type": "list", "list": { "items": [ { "title": "Section 1", "actions": [ { "type": "postback", "postback": { "payload": "postback-action-payload-1", "text": "Postback action 1" } }, { "type": "postback", "postback": { "payload": "postback-action-payload-2", "text": "Postback action 2" } } ] }, { "title": "Section 2", "actions": [ { "type": "postback", "postback": { "payload": "postback-action-payload-3", "text": "Postback action 3" } }, { "type": "postback", "postback": { "payload": "postback-action-payload-4", "text": "Postback action 4" } } ] } ], "title": "List title", "altText": "List alt text", "text": "List text" } }

List message with sections and custom button label

{ "type": "list", "list": { "items": [ { "title": "Section 1", "actions": [ { "type": "postback", "postback": { "payload": "postback-action-payload-1", "text": "Postback action 1", "metadata": { "description": { "label": "Postback action description 1" } } } }, { "type": "postback", "postback": { "payload": "postback-action-payload-2", "text": "Postback action 2", "metadata": { "description": { "label": "Postback action description 2" } } } } ] }, { "title": "Section 2", "actions": [ { "type": "postback", "postback": { "payload": "postback-action-payload-3", "text": "Postback action 3", "metadata": { "description": { "label": "Postback action description 3" } } } }, { "type": "postback", "postback": { "payload": "postback-action-payload-4", "text": "Postback action 4", "metadata": { "description": { "label": "Postback action description 4" } } } } ] } ], "title": "List title", "altText": "List alt text", "text": "List text", "metadata": { "button": { "label": "Show options" } } } }

Carousel

Carousel messages must contain:

1. body.carousel.text - this contains the text for the bubble before the carousel

2. Between 2-10 cards.

   1. mediaUrl where media type is either all image or all video

      1. Image types - image/jpeg, image/png

      2. Video types - video/mp4, video/3gpp

   2. Card title

   3. One link action button

{ "type": "carousel", "carousel": { "text": "Here is a media carousel with link actions", "items": [ { "title": "Card 1", "mediaUrl": "https://bird.com/images/image1.jpg", "actions": [ { "type": "link", "link": { "text": "Visit Bird", "url": "https://www.bird.com" } } ] }, { "title": "Card 2", "mediaUrl": "https://bird.com/images/image2.jpg", "actions": [ { "type": "link", "link": { "text": "Visit Bird", "url": "https://www.bird.com" } } ] } ] } }

ReplyTo

You can send any outbound message as a reply to a previous message by setting the replyTo object as shown below. The replyTo.id should be set to the id of a received message and the replyTo.type should be set to "message"

{
 "receiver": {
   "contacts": [
     {
       "identifierValue": "[phone]"
     }
   ]
 },
 "body": {...},
 "replyTo": {
   "id": "<recievedmessageid>",
   "type": "message"
 }
}

ReplyTo with a text message

{ "type": "text", "text": { "text": "Single text message" }, "replyTo": { "id": "1e7b70ab-3dcc-48f4-a6f6-63a493f6134c", "type": "message" } }

ReplyTo with an image message

{ "type": "image", "image": { "images": [ { "altText": "Label of first image", "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FRPPgQAGyZE7rvIh3WM2Z%2Fimage2.avif?alt=media" } ] }, "replyTo": { "id": "1e7b70ab-3dcc-48f4-a6f6-63a493f6134c", "type": "message" } }

ReplyTo with text message with postback actions

{ "type": "text", "text": { "text": "Single text message with postback actions", "actions": [ { "type": "postback", "postback": { "text": "Postback action 1", "payload": "postback-payload-1" } }, { "type": "postback", "postback": { "text": "Postback action 2", "payload": "postback-payload-2" } } ] }, "replyTo": { "id": "1e7b70ab-3dcc-48f4-a6f6-63a493f6134c", "type": "message" } }

Template

Template is the only message type that can be sent by a business to a recipient outside the customer service window, however, a prior opt-in is required. Templates must be active in Studio and, therefore, pre-approved by Meta, before they are used. It's also important to note that the code snippets below must be set in the message template field

{
 "receiver": {
   "contacts": [
     {
       "identifierValue": "[phone]"
     }
   ]
 },
 "template": {...}
}

Text template with variable

	{ "projectId":"ce6a2fd6-b2fa-4f5a-a2cd-f3bd15883318", "version":"latest", "locale":"en", "parameters":[ { "type":"string", "key":"name", "value":"Robert" } ] }

Image template with button and variables

	{ "projectId":"7b492653-450b-4e97-b5e4-3827868e7438", "version":"latest", "locale":"en", "parameters":[ { "type":"string", "key":"imageURL", "value":"https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FRPPgQAGyZE7rvIh3WM2Z%2Fimage2.avif?alt=media" } ] }

Image with a variable in a button

	{ "projectId":"6449eb42-dffb-41c2-81a1-7fd956d2e7a6", "version":"e0e9190c-c3e7-4026-8fc3-d28a77aa1a52", "locale":"en", "parameters":[ { "type":"string", "key":"name", "value":"Robert" }, { "type":"string", "key":"url", "value":"?campaignid=123456" } ] }