LogoLogo
No-code docsResources
  • 🖥️Welcome to the Bird API Docs
  • API Access
    • Access Policies
    • Access Roles
    • API Authorization
    • Common API usage
  • Conversations API
    • API reference
      • Channel configuration
        • Get conversations configuration
        • Update conversations configuration
      • Conversations messaging
        • Create conversation message
        • List conversation messages
        • Get conversation message
        • Update conversation message
        • Delete conversation message
        • Create pre-signed upload
      • Conversations management
        • Create conversation
        • List conversations
        • Get conversation
        • Update conversation
        • Delete conversation
      • Conversation Participants
        • Add participant to conversation
        • List participants
        • Get participant by ID
        • Get participant by identifier key and value
        • Update participant by ID
        • Update participant by identifier key and value
        • Delete participant
        • List participant conversations by ID
        • List participant conversations by identifier key and value
      • Workspace settings
        • Get antispam setting
        • Update antispam setting
        • Create allow/block rule
        • Get allow/block rule
        • List allow/block rules
        • Update allow/block rule
        • Delete allow/block rule
        • Add allow/block rules in bulk
        • Get allow/block bulk upload status
      • Events
  • Collaborations API
    • API reference
      • Agent Management
      • Team Management
      • Feeds
      • Feed item activity
      • Tags
      • Automation Rules
      • Business Hours
      • Capacity Rules
      • Routing Queues
      • Skills
      • SLA Policies
      • Macros
      • Sender Profiles
      • Ticket fields
  • Channels API
    • Supported channels
      • Programmable WhatsApp
        • Sending WhatsApp messages
        • Customer service window
        • Receiving messages
        • Message interactions
        • WhatsApp ISV integration
          • Setting up your customer workspaces
            • API Access
            • Associating your Facebook solution ID and business ID with your Bird CRM Organization
            • Creating a workspace for your customer
            • Buying a number through Bird
            • Subscribing to channel created webhooks
          • WhatsApp channel onboarding
            • Setting up the WhatsApp Embedded flow
            • Install WhatsApp phone number in Bird CRM
            • Subscribe to channel webhooks
      • Programmable SMS
        • Installing an SMS channel
          • US 10DLC API Installation
          • Toll-Free Numbers Verification API
        • Sending SMS messages
        • Receiving messages
        • Twilio Exit API
          • Using Twilio PHP SDK
          • Using Twilio Go SDK
          • Using Twilio Ruby SDK
        • Sinch Exit API
      • Programmable RCS
        • Sending messages
        • Receiving messages
        • Message interactions
      • Programmable Email
        • Sending Emails
        • Receiving messages
        • Message status
        • Message interactions
      • Programmable Line
        • Sending messages
        • Receiving messages
        • Message interactions
      • Programmable Telegram
        • Sending messages
        • Receiving messages
        • Message interactions
    • Message types
      • Text
      • Images
      • Files
      • List
      • Carousel
      • Template
    • Message status and interactions
      • Message Failure Codes
      • Message Failure Sources
        • SMS Platform Extended Error Codes
    • Send batch messages
    • API reference
      • Channel Groups
      • Messaging
      • Channels management
      • Channel connectors
      • Navigators
      • Compliance Keywords Messages
      • Conversions Sharing
      • Events
    • Rate Limit
  • Voice API
    • Installing a Voice channel
    • Voice Calls API
      • Initiate an outbound call
      • List calls from a channel
      • Get a call
      • Update a call
      • Answer a call
      • Ring a call
      • Hangup a call
      • Play a message in a call
      • Say Text-To-Speech (TTS)
      • Gather DTMF from a call
      • Forward a call
      • Record a Call
      • Record a call session
      • Update a call recording
      • List call recordings of a call
      • Get a call recording
      • Get a call insights
      • Get calls log
    • Recordings API
      • List Recordings
      • Get a Recording
      • Delete a Recording
      • List recording storage metrics
    • Transcriptions API
      • Initiate a Transcription
      • List Transcriptions
      • Get a Transcription
      • Delete a Transcription
    • Voice webhooks
    • Flash Calling API
  • Verify API
    • Verify API: Quick Start
  • Contacts API
    • Tracking Contact Events
      • API Reference
        • Get configuration
        • Track events
    • API reference
      • Manage workspace contacts
        • Create a contact
        • Get a contact
        • List contacts
        • Search contact by identifier
        • Update a contact
        • Create or update a contact by identifier
        • Delete a contact
      • Manage contact identifiers
        • Create contact identifier
        • List contact identifiers
        • Delete contact identifier
      • Manage contact attribute definition
        • Create attribute definition
        • Get attribute definition
        • List attribute definitions
      • Manage contact lists
        • Create a list
        • Get a list
        • List lists
        • Update a list
        • Delete a list
        • Add contacts to a list
        • Get contact list memberships
        • List contacts in a list
        • Remove contacts from a list
      • Lookup
        • Network/Country information for a phone number
  • Numbers API
    • API reference
      • Search Available Numbers
      • Buy a Number
      • List your Numbers
      • Get Long Code Number Details
      • Manage Endpoint Subscriptions
        • Cancel Number Subscription
      • Manage Endpoint Compliance Requirements
        • List Workspace compliace Requirements
        • Get Workspace Compliace Requirements
        • Update Workspace Compliace Requirements
      • 10DLC Compliance
        • Brands - Organization
          • Create a brand
          • List all brands
          • Get a brand
          • Update a brand
          • Delete a brand
          • Create a brand vetting
        • Brands - workspace
          • Create a brand
          • List all brands
          • Get a brand
          • Update a brand
          • Delete a brand
          • Create a brand vetting
          • List brand vettings
        • Campaigns
          • Optional: acting as Reseller
          • Create a campaign
          • List all campaigns
          • Get a campaign
          • Update a campaign
          • Delete a campaign
        • TCR Enums
        • Events
      • Toll-Free Numbers Verification API
      • Long Code Numbers
      • Short Code Numbers
      • Alphanumeric Senders
      • Events
  • Know-Your-Customer (KYC) API
    • List KYC forms
    • Get KYC form
    • Create KYC form entry
    • Update KYC form entry
    • List KYC form entries
    • Get a KYC form entry details
  • Reporting API
    • API reference
      • Channel Metrics
      • Flow Run Metrics
      • Wallet Metrics
      • Campaign Metrics
      • Message Metrics
  • Accounts API
    • API reference
      • Current user
        • Change password
        • Presigned upload
        • Memberships
        • Sessions
        • Configurations
          • Groups
            • Keys
      • IAM policies
      • Organizations
        • Upload media
        • Profile
        • Workspaces
        • Users
        • Access keys
        • Organization roles
        • Organization policies
        • Teams
          • Members
        • Approvals
          • Runs
            • Reviews
        • Configurations
          • Groups
            • Keys
      • Region groups
  • Touchpoints API
    • Supported Projects
      • Whatsapp Approved Message Templates
        • Creating WhatsApp Message templates
          • Text template blocks
          • Blocks Documentation
    • API reference
      • Projects
      • Message Templates
  • Notifications API
    • API Reference
      • Webhook subscriptions
        • Create a webhook subscription
        • List available webhook events
        • Get a webhook subscription
        • List webhook subscriptions
        • Update a webhook subscription
        • Delete a webhook subscription
        • Verifying a webhook subscription
        • Webhook subscription logs
  • Knowledge Base (KB) API
    • API reference
      • Documents
      • Folders
        • Import
      • Search
      • Presigned upload
  • Email API
    • Transmissions
    • Metrics
    • Events
    • Recipient Validation
    • SMTP API
  • Connectivity platform migration guide
    • Channels API and Conversations API
    • Migrating conversations API actions
    • Migrating WhatsApp channels
  • Client SDKs
    • Applications
    • Contact Profiles
      • Signed Identity
    • Push notifications
      • Quick Start
      • Subscribe contacts to push notification campaigns
      • Notification Display Priority
    • Event Tracking
      • Quick Start
      • Track Events
        • App
        • Audiences
        • Conference
        • Ecommerce
        • Hospitality
        • Lists
        • Messaging
        • Payments
        • Subscription
        • Suppressions
        • Survey
        • Web
    • App Inbox
      • Quick Start
      • Usage
      • Subscribe contacts to app inbox campaigns
    • SDK Integration
      • Android SDK
        • Notification Interactions
      • Swift SDK
        • Notification Interactions
      • Web SDK
        • Quick Start
        • Usage
        • API Reference
          • IdentityManager
          • BirdSdkApi
          • BirdTracker
            • Ecommerce
            • Conference
            • Messaging
            • Suppressions
            • Subscription
            • Survey
            • Web
            • Audiences
        • Web Push Notifications
          • Notification Interactions
  • Quickstarts
    • Conversations
    • Send an SMS message
    • Send an Email message
    • Send a WhatsApp message
Powered by GitBook
On this page

Was this helpful?

  1. Channels API
  2. API reference

Messaging

Last updated 7 months ago

Was this helpful?

Sending messages

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

When you send a message, a contact is automatically created with a contactId matching the receiver's identifier if one doesn't already exist. For instance, sending an email generates a contact with an email identifier, while sending an SMS creates one with a phone number identifier.

Multiple recipient messages are only possible through the Email platform. For other platforms, a message with multiple reciever entries will be rejected.

Body

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

Template

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

Uploading media

When sending messages that contain media links these must be publicly accessible. Otherwise you can upload media by creating requesting a pre-signed media URL. Firstly make a POST request to the following endpoint with the content type of the media you will be uploading set in the request body.

There are two methods for generating a presigned URL: one is channel-independent, allowing it to be used across any channel, while the other restricts usage to a specified channel ID.

From the response you will get the following details:

mediaUrl: This will be the URL you set in any message bodies where you send the uploaded media

uploadUrl: This is the URL you will need to make a request to to upload your media file

uploadMethod: This is the HTTP method to make an upload i.e. POST

uploadFormData: Set this as the fields in form-data of your POST request along with an additional field called file. This should include your file data. An example using CURL

No need to specify any AccessKey on the below call as all the required data is provided in the form data.

curl -X POST \
  # uploadFormData
  -F Content-Type='...' \
  -F acl='private' \
  -F bucket='channels..' \
  -F key='b2d..b123' \
  -F policy='eyJle...dfQ==' \
  -F x-amz-algorithm='AWS4-HMAC-SHA256' \
  -F x-amz-credential='ASIA..' \
  -F x-amz-date='20230501T192504Z' \
  -F x-amz-meta-allowed-paths='workspace\b2..' \
  -F x-amz-meta-channel-id='ac0..f19e' \
  -F x-amz-security-token='IQoo..qqq' \
  -F x-amz-signature='RcU9...XLw=' \
  # the file to upload
  -F file=@local-filename.txt \
  # the URL
  https://channels...s3.amazonaws.com/

Once you have uploaded the file using the mediaUrl, this should be used as the URL when sending messages with media.

Retrieving messages

Retrieve a list of messages of a channel

Retrieve list of messages of a workspace

Retrieve a single message

Retrieve all message interactions on a message

Retrieving media

Retrieve pre-signed media uploads

Retrieve media from incoming messages

For media sent to your channel you can download this media from the following endpoint

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

For media that you have to be sent in a channels message you can retrieve this as follows

message template
uploaded
access key

List messages by channel ID

get

It retrieves a list of messages from a given channel ID

Authorizations
Path parameters
workspaceIdstring · uuidRequired

The ID of the workspace

channelIdstring · uuidRequired

The ID for a channel

Query parameters
limitinteger · min: 1 · max: 1000Optional

Limits the number of results to return

Default: 10
pageTokenstring · max: 8000Optional

Pagination token that keeps of track of the current position in the list

reversebooleanOptional

Order in which to retrieve the results

Default: false
platformany ofOptional

Filter based on platform name

string · min: 3 · max: 60OptionalPattern: ^[A-Za-z0-9-]+$
or
string[]Optional
directionstring · enumOptionalPossible values:
idstring · uuid[]Optional
navigatorIdstring · uuidOptional
startAtstring · date-timeOptional

Start date for the query

endAtstring · date-timeOptional

End date for the query

fromstring[]Optional

sender identifier for the message

tostring[]Optional

recipient identifier for the message

failureCodeinteger[]Optional
failureSourceCodestring[]Optional
failureSourceNamestring[]Optional
countryCodestring[]Optional
tagstring[]Optional

Filter based on tag

emailSubjectstringOptional

Full text search on email subject

batchIdstring · uuidOptional

The ID for a batch

Responses
200
OK
Responseall of
404
The request did not pass validation
application/json
422
The request did not pass validation
application/json
get
GET /workspaces/{workspaceId}/channels/{channelId}/messages HTTP/1.1
Host: 
Authorization: Bearer jwt
Accept: */*
{
  "startAt": "2025-05-29T06:14:56.392Z",
  "endAt": "2025-05-29T06:14:56.392Z",
  "nextPageToken": "text",
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "channelId": "123e4567-e89b-12d3-a456-426614174000",
      "sender": {
        "connector": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierValue": "text",
          "annotations": {
            "name": "text"
          },
          "types": [
            "text"
          ]
        }
      },
      "receiver": {
        "connector": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierValue": "text",
          "annotations": {
            "name": "text"
          },
          "types": [
            "text"
          ]
        }
      },
      "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"
          }
        },
        "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"
        }
      },
      "reference": "my-own-identifier",
      "parts": [
        {
          "platformReference": "text"
        }
      ],
      "status": "accepted",
      "reason": "text",
      "direction": "incoming",
      "origin": {
        "type": "text",
        "id": "text"
      },
      "replyTo": {
        "id": "text",
        "order": 1,
        "type": "message"
      },
      "lastStatusAt": "2025-05-29T06:14:56.392Z",
      "createdAt": "2025-05-29T06:14:56.392Z",
      "updatedAt": "2025-05-29T06:14:56.392Z",
      "details": "text",
      "failure": {
        "code": 1,
        "description": "Unsupported media type",
        "source": {
          "code": "text",
          "name": "text"
        }
      },
      "tags": [
        "text"
      ],
      "shortLinks": {
        "domain": "text"
      },
      "scheduledFor": "2025-05-29T06:14:56.392Z",
      "body": {
        "type": "text",
        "text": {
          "text": "text",
          "attachments": [
            {
              "mediaUrl": "https://example.com",
              "filename": "text",
              "inline": true
            }
          ],
          "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",
                    "length": 1
                  }
                ]
              }
            },
            "telegram": {
              "parseMode": "Markdown"
            }
          }
        }
      }
    }
  ]
}

Get message by message ID

get

Get a channel message

Authorizations
Path parameters
workspaceIdstring · uuidRequired

The ID of the workspace

messageIdstring · uuidRequired

The ID for a message

channelIdstring · uuidRequired

The ID for a channel

Responses
200
OK
application/json
Responseall of
and
any ofOptional
or
404
The request did not pass validation
application/json
get
GET /workspaces/{workspaceId}/channels/{channelId}/messages/{messageId} HTTP/1.1
Host: 
Authorization: Bearer jwt
Accept: */*
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "channelId": "123e4567-e89b-12d3-a456-426614174000",
  "sender": {
    "connector": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text",
      "annotations": {
        "name": "text"
      },
      "types": [
        "text"
      ]
    }
  },
  "receiver": {
    "connector": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text",
      "annotations": {
        "name": "text"
      },
      "types": [
        "text"
      ]
    }
  },
  "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"
      }
    },
    "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"
    }
  },
  "reference": "my-own-identifier",
  "parts": [
    {
      "platformReference": "text"
    }
  ],
  "status": "accepted",
  "reason": "text",
  "direction": "incoming",
  "origin": {
    "type": "text",
    "id": "text"
  },
  "replyTo": {
    "id": "text",
    "order": 1,
    "type": "message"
  },
  "lastStatusAt": "2025-05-29T06:14:56.392Z",
  "createdAt": "2025-05-29T06:14:56.392Z",
  "updatedAt": "2025-05-29T06:14:56.392Z",
  "details": "text",
  "failure": {
    "code": 1,
    "description": "Unsupported media type",
    "source": {
      "code": "text",
      "name": "text"
    }
  },
  "tags": [
    "text"
  ],
  "shortLinks": {
    "domain": "text"
  },
  "scheduledFor": "2025-05-29T06:14:56.392Z",
  "body": {
    "type": "text",
    "text": {
      "text": "text",
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": true
        }
      ],
      "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",
                "length": 1
              }
            ]
          }
        },
        "telegram": {
          "parseMode": "Markdown"
        }
      }
    }
  }
}

List message interactions

get

List message interactions

Authorizations
Path parameters
workspaceIdstring · uuidRequired

The ID of the workspace

messageIdstring · uuidRequired

The ID for a message

channelIdstring · uuidRequired

The ID for a channel

Responses
200
OK
application/json
404
The request did not pass validation
application/json
get
GET /workspaces/{workspaceId}/channels/{channelId}/messages/{messageId}/interactions HTTP/1.1
Host: 
Authorization: Bearer jwt
Accept: */*
{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "messageId": "123e4567-e89b-12d3-a456-426614174000",
      "channelId": "123e4567-e89b-12d3-a456-426614174000",
      "platformId": "text",
      "type": "clicked",
      "messageReference": "text",
      "messagePartsCount": 1,
      "messageTags": [
        "text"
      ],
      "receiver": {
        "connector": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierValue": "text",
          "annotations": {
            "name": "text"
          },
          "types": [
            "text"
          ]
        }
      },
      "createdAt": "2025-05-29T06:14:56.392Z",
      "details": "text",
      "context": {
        "id": "text",
        "type": "text",
        "tags": [
          "text"
        ]
      },
      "metadata": {
        "link": {
          "name": "text",
          "url": "text"
        },
        "button": {
          "payload": "text"
        },
        "reaction": {
          "emoji": "text",
          "action": "text"
        },
        "conversion": {
          "type": "text",
          "status": "text",
          "method": "text",
          "timestamp": "2025-05-29T06:14:56.392Z"
        },
        "prefetched": true,
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ]
}

Send a message

post

Send a message to a channel

Authorizations
Path parameters
workspaceIdstring · uuidRequired

The ID of the workspace

channelIdstring · uuidRequired

The ID for a channel

Body
all ofOptional
and
any ofOptional
object · ChannelMessageCreateWithTemplateOptional
or
object · ChannelMessageCreateWithBodyOptional
Responses
202
Message was accepted for processing
application/json
Responseall of
and
any ofOptional
or
400
The request did not pass validation
application/json
404
The request did not pass validation
application/json
409
Creating the message was not possible because of conflicting conditions
application/json
422
The request did not pass validation
application/json
post
POST /workspaces/{workspaceId}/channels/{channelId}/messages HTTP/1.1
Host: 
Authorization: Bearer jwt
Content-Type: application/json
Accept: */*
Content-Length: 2663

{
  "sender": {
    "connector": {
      "identifierValue": "channels@bird.com",
      "annotations": {
        "name": "text"
      }
    }
  },
  "receiver": {
    "contacts": [
      {
        "id": "a1405560-c8d3-4b1a-877d-3f449ad95352",
        "identifierKey": "emailaddress",
        "identifierValue": "channels@bird.com",
        "type": "cc",
        "identifiers": [
          {
            "identifierKey": "emailaddress",
            "identifierValue": "channels@bird.com"
          }
        ],
        "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"
    },
    "variables": {
      "default": "text",
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "utmParameters": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "parameters": [
      {
        "type": "string",
        "key": "text",
        "value": "text"
      }
    ],
    "settings": {
      "useMmLite": 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"
      }
    },
    "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
        }
      ],
      "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"
        }
      }
    }
  },
  "notification": {
    "url": "text"
  },
  "capFrequency": true,
  "enableLinkTracking": true,
  "ignoreQuietHours": true,
  "ignoreGlobalHoldout": true,
  "tags": [
    "text"
  ],
  "shortLinks": {
    "domain": "text"
  },
  "scheduledFor": "2025-05-29T06:14:56.392Z",
  "validity": 1
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "channelId": "123e4567-e89b-12d3-a456-426614174000",
  "sender": {
    "connector": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text",
      "annotations": {
        "name": "text"
      },
      "types": [
        "text"
      ]
    }
  },
  "receiver": {
    "connector": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text",
      "annotations": {
        "name": "text"
      },
      "types": [
        "text"
      ]
    }
  },
  "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"
      }
    },
    "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"
    }
  },
  "reference": "my-own-identifier",
  "parts": [
    {
      "platformReference": "text"
    }
  ],
  "status": "accepted",
  "reason": "text",
  "direction": "incoming",
  "origin": {
    "type": "text",
    "id": "text"
  },
  "replyTo": {
    "id": "text",
    "order": 1,
    "type": "message"
  },
  "lastStatusAt": "2025-05-29T06:14:56.392Z",
  "createdAt": "2025-05-29T06:14:56.392Z",
  "updatedAt": "2025-05-29T06:14:56.392Z",
  "details": "text",
  "failure": {
    "code": 1,
    "description": "Unsupported media type",
    "source": {
      "code": "text",
      "name": "text"
    }
  },
  "tags": [
    "text"
  ],
  "shortLinks": {
    "domain": "text"
  },
  "scheduledFor": "2025-05-29T06:14:56.392Z",
  "body": {
    "type": "text",
    "text": {
      "text": "text",
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": true
        }
      ],
      "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",
                "length": 1
              }
            ]
          }
        },
        "telegram": {
          "parseMode": "Markdown"
        }
      }
    }
  }
}

Create a presigned media upload

post
Authorizations
Path parameters
workspaceIdstring · uuidRequired

The ID of the workspace

Body
contentTypestring · min: 1Required
Responses
200
OK
application/json
404
The request did not pass validation
application/json
422
The request did not pass validation
application/json
post
POST /workspaces/{workspaceId}/channel-media/presigned-upload HTTP/1.1
Host: 
Authorization: Bearer jwt
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "contentType": "text"
}
{
  "mediaUrl": "https://example.com",
  "uploadUrl": "https://example.com",
  "uploadMethod": "text",
  "uploadFormData": {}
}

Create a presigned media upload

post
Authorizations
Path parameters
workspaceIdstring · uuidRequired

The ID of the workspace

channelIdstring · uuidRequired

The ID for a channel

Body
contentTypestring · min: 1Required
Responses
200
OK
application/json
404
The request did not pass validation
application/json
422
The request did not pass validation
application/json
post
POST /workspaces/{workspaceId}/channels/{channelId}/presigned-upload HTTP/1.1
Host: 
Authorization: Bearer jwt
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "contentType": "text"
}
{
  "mediaUrl": "https://example.com",
  "uploadUrl": "https://example.com",
  "uploadMethod": "text",
  "uploadFormData": {}
}

Get message media

get

Get media from a message

Authorizations
Path parameters
workspaceIdstringRequired
messageIdstringRequired
fileIdstringRequired
Query parameters
redirectbooleanOptional
Responses
200
Return file location
302
Redirect to file location
400
Bad request
application/json
404
The resource is not found
application/json
get

No content

GET /workspaces/{workspaceId}/messages/{messageId}/media/{fileId} HTTP/1.1
Host: 
Authorization: Bearer jwt
Accept: */*

List messages by workspace ID

get

It retrieves a list of messages from a given workspace ID

Authorizations
Path parameters
workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters
limitinteger · min: 1 · max: 1000Optional

Limits the number of results to return

Default: 10
channelIdstring[]Optional

The ID for a channel

pageTokenstring · max: 8000Optional

Pagination token that keeps of track of the current position in the list

reversebooleanOptional

Order in which to retrieve the results

Default: false
platformany ofOptional

Filter based on platform name

string · min: 3 · max: 60OptionalPattern: ^[A-Za-z0-9-]+$
or
string[]Optional
directionstring · enumOptionalPossible values:
idstring · uuid[]Optional
startAtstring · date-timeOptional

Start date for the query

endAtstring · date-timeOptional

End date for the query

fromstring[]Optional

sender identifier for the message

tostring[]Optional

recipient identifier for the message

failureCodeinteger[]Optional
failureSourceCodestring[]Optional
failureSourceNamestring[]Optional
countryCodestring[]Optional
tagstring[]Optional

Filter based on tag

emailSubjectstringOptional

Full text search on email subject

Responses
200
OK
Responseall of
404
The request did not pass validation
application/json
422
The request did not pass validation
application/json
get
GET /workspaces/{workspaceId}/channels/messages HTTP/1.1
Host: 
Authorization: Bearer jwt
Accept: */*
{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "channelId": "123e4567-e89b-12d3-a456-426614174000",
      "sender": {
        "connector": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierValue": "text",
          "annotations": {
            "name": "text"
          }
        }
      },
      "receiver": {
        "connector": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierValue": "text",
          "annotations": {
            "name": "text"
          }
        }
      },
      "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"
          }
        },
        "navigatorId": "123e4567-e89b-12d3-a456-426614174000",
        "navigatorMessageId": "123e4567-e89b-12d3-a456-426614174000"
      },
      "reference": "text",
      "parts": [
        {
          "platformReference": "text"
        }
      ],
      "status": "accepted",
      "reason": "text",
      "direction": "incoming",
      "replyTo": {
        "id": "text",
        "order": 1,
        "type": "message"
      },
      "lastStatusAt": "2025-05-29T06:14:56.392Z",
      "createdAt": "2025-05-29T06:14:56.392Z",
      "updatedAt": "2025-05-29T06:14:56.392Z",
      "details": "text",
      "failure": {
        "code": 1,
        "source": {
          "code": "text",
          "name": "text"
        }
      },
      "tags": [
        "text"
      ],
      "shortLinks": {
        "domain": "text"
      },
      "scheduledFor": "2025-05-29T06:14:56.392Z",
      "body": {
        "type": "text",
        "text": {
          "text": "text",
          "attachments": [
            {
              "mediaUrl": "https://example.com",
              "filename": "text",
              "inline": true
            }
          ],
          "actions": [
            {
              "type": "link",
              "link": {
                "text": "text",
                "url": "https://example.com"
              }
            }
          ],
          "metadata": {
            "subject": "text",
            "headers": {
              "ANY_ADDITIONAL_PROPERTY": "text"
            },
            "whatsapp": {
              "previewUrl": true
            },
            "line": {
              "emoji": {
                "items": [
                  {
                    "index": 1,
                    "productId": "text",
                    "emojiId": "text",
                    "length": 1
                  }
                ]
              }
            }
          }
        }
      }
    }
  ],
  "nextPageToken": "text"
}
  • Sending messages
  • POSTSend a message
  • Body
  • Template
  • Uploading media
  • POSTCreate a presigned media upload
  • POSTCreate a presigned media upload
  • Retrieving messages
  • Retrieve a list of messages of a channel
  • GETList messages by channel ID
  • Retrieve list of messages of a workspace
  • GETList messages by workspace ID
  • Retrieve a single message
  • GETGet message by message ID
  • Retrieve all message interactions on a message
  • GETList message interactions
  • Retrieving media
  • Retrieve pre-signed media uploads
  • Retrieve media from incoming messages
  • GETGet message media