> ## Documentation Index > Fetch the complete documentation index at: https://docs.periskope.app/llms.txt > Use this file to discover all available pages before exploring further. # Broadcast Message > Sends the same message (text, media or poll) to many chats — from chat_ids, or every chat carrying the given label. One credit per recipient; rejected up front when credits are insufficient. ## OpenAPI ````yaml api-reference/openapi-generated.json POST /v1/message/broadcast openapi: 3.0.3 info: title: Periskope API version: 1.0.0 description: >- Periskope external API. Responses use a flat, unwrapped shape: most endpoints return the resource at the top level, and list endpoints return a wrapper object with pagination inline (e.g. `{ from, to, count, chats: [...] }`). The documented response schemas describe these shapes directly. servers: - url: https://api.periskope.app security: - bearerAuth: [] paths: /v1/message/broadcast: post: tags: - Messages summary: Broadcast a message to many chats description: >- Sends the same message (text, media or poll) to many chats — from chat_ids, or every chat carrying the given label. One credit per recipient; rejected up front when credits are insufficient. operationId: broadcastMessage parameters: - schema: type: string example: '919876543210' description: >- Optional. Scope results to a single phone: country code + number without symbols or spaces (e.g. 911111111111), or a phone_id (phone-xxxxxxxxxxxx). Omit to return data across all phones the API token can access. required: false description: >- Optional. Scope results to a single phone: country code + number without symbols or spaces (e.g. 911111111111), or a phone_id (phone-xxxxxxxxxxxx). Omit to return data across all phones the API token can access. name: x-phone in: header requestBody: content: application/json: schema: type: object properties: chat_ids: anyOf: - type: array items: type: string - type: string description: >- Recipients of the broadcast, as an array of chat ids (or a single comma-separated string). For group chats, the chat_id ending with @g.us; for 1-1 chats, country code + number of the contact, optionally suffixed with @c.us (e.g. 911111111111 or 911111111111@c.us). Duplicates are removed. Either chat_ids or label is required. example: - 911111111111@c.us - 120363000000000000@g.us label: type: string description: >- Name of a chat label — when chat_ids is empty, the broadcast is sent to every chat carrying this label. Ignored when chat_ids is provided. example: newsletter message: type: string description: >- The text body of the message, or the caption when media is provided. Supports the basic WhatsApp markdown formatting (*bold*, _italic_, ~strikethrough~, ```monospace```). example: Hello World media: type: object properties: type: type: string enum: - image - video - document - audio - ptt description: >- Kind of media being sent: 'image', 'video', 'document', 'audio', or 'ptt' (push-to-talk voice note). Determines the message_type of the resulting message. example: image url: type: string description: >- Publicly accessible URL that hosts the content to be sent. Provide either url or filedata, not both. example: https://example.com/files/image.png filedata: type: string description: >- Raw bytes of the file, encoded as base64. Alternative to url — provide either url or filedata, not both. example: iVBORw0KGgoAAAANSUhEUgAA... mimetype: type: string description: >- MIME type of the media file (e.g. image/png, video/mp4, text/csv). Recommended when sending filedata. example: image/png filename: type: string description: >- Filename of the media, shown in the chat (mainly relevant for document messages). Defaults to the last path segment of url. example: image.png required: - type description: >- Media to send — a document, image, video, audio file or voice note. Provide either a public url or base64 filedata. The message text, when given, becomes the caption. poll: type: object properties: pollName: type: string minLength: 1 description: The question or title of the poll example: Which day suits everyone for the demo? pollOptions: type: array items: type: string minItems: 2 maxItems: 12 description: >- The answer options of the poll — between 2 and 12 entries example: - Monday - Wednesday - Friday options: type: object properties: allowMultipleAnswers: type: boolean description: >- When true, respondents can select multiple options. Defaults to single choice. example: true pollId: type: string description: >- Optional unique identifier of the poll — useful to correlate the same poll sent across multiple chats example: poll-2026-demo-day description: Additional options of the poll required: - pollName - pollOptions description: >- Poll to send instead of a plain message. The resulting message has message_type poll_creation. reply_to: type: string description: >- message_id of an existing message in the chat to reply to. The sent message quotes it. example: >- true_911111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA options: type: object properties: hide_url_preview: type: boolean description: >- When true, disables the automatic link preview for URLs contained in the message example: true description: Additional sending options variables: type: array items: type: object properties: chat_id: type: string minLength: 1 description: The recipient chat these variable values apply to example: 911111111111@c.us values: type: object description: >- Map of variable name to the value substituted for this chat. Must cover exactly the {{placeholders}} used in the message — no missing and no extra keys. example: name: Jane order_id: ORD-1042 required: - chat_id - values description: >- Per-chat values for the {{placeholders}} used in the message. Required when the message contains placeholders: every recipient chat must have an entry covering exactly the placeholder names — missing or extra keys are rejected. example: - chat_id: 911111111111@c.us values: name: Jane order_id: ORD-1042 scheduled_at: type: string description: >- UTC date and time to start the broadcast at, in ISO 8601 format. Must be in the future. Omit to start immediately. example: '2026-02-06T11:21:00Z' delay: type: number minimum: 0 maximum: 60 description: >- Time interval between consecutive messages, in seconds (0-60). Defaults to about 1 second when omitted. example: 10 org_phones: type: array items: type: string description: >- Org phones to send the broadcast from — recipients are distributed across them. Takes precedence over the x-phone header. When neither is given, every available phone of the org is used. example: - 911111111111@c.us responses: '200': description: The created broadcast content: application/json: schema: type: object properties: broadcast_id: type: string description: >- Id of the created broadcast. Use it to track progress via POST /message/queues or to cancel/stop via DELETE /message/broadcast/{broadcast_id}. Messages produced by the broadcast carry it as broadcast_id. example: 00000000-0000-0000-0000-000000000000 hint: type: string description: Human-readable pointer on how to track the broadcast example: >- You can track broadcast status by making a POST request to /messages/queues with { "broadcast_id": "00000000-0000-0000-0000-000000000000" } as body examples: default: summary: Response body value: broadcast_id: 00000000-0000-0000-0000-000000000000 hint: >- You can track broadcast status by making a POST request to /messages/queues with { "broadcast_id": "00000000-0000-0000-0000-000000000000" } as body '401': description: Invalid, expired or missing API token content: application/json: examples: error: summary: Invalid, expired or missing API token value: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 schema: type: object properties: code: type: string example: UNAUTHORIZED_ERROR message: type: string example: Invalid bearer auth token status: type: integer example: 401 example: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 '422': description: Request validation failed content: application/json: examples: error: summary: Request validation failed value: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required schema: type: object properties: code: type: string example: VALIDATION_ERROR message: type: string example: Request validation failed status: type: integer example: 422 fields: type: object additionalProperties: type: object properties: message: type: string value: {} example: body.chat_id: message: chat_id is required example: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required '429': description: Rate limit exceeded content: application/json: examples: error: summary: Rate limit exceeded value: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 schema: type: object properties: code: type: string example: RATE_LIMIT_ERROR message: type: string example: You can only make 100 requests per second status: type: integer example: 429 example: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 '500': description: Internal server error content: application/json: examples: error: summary: Internal server error value: code: UNKNOWN_ERROR message: Internal server error status: 500 schema: type: object properties: code: type: string example: UNKNOWN_ERROR message: type: string example: Internal server error status: type: integer example: 500 example: code: UNKNOWN_ERROR message: Internal server error status: 500 security: - bearerAuth: [] x-codeSamples: - lang: typescript label: TypeScript source: |- import { PeriskopeApi } from '@periskope/periskope-client'; const client = new PeriskopeApi({ authToken: 'YOUR_API_KEY', phone: '919876543210', // the phone to act with (x-phone) }); async function main() { const response = await client.messages.broadcastMessage({ chat_ids: [ '911111111111@c.us', '120363000000000000@g.us', ], }); console.log(response); } main(); - lang: bash label: cURL source: |- curl -X POST 'https://api.periskope.app/v1/message/broadcast' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'x-phone: 919876543210' \ -H 'Content-Type: application/json' \ -d '{ "chat_ids": [ "911111111111@c.us", "120363000000000000@g.us" ] }' components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Periskope API token, sent as `Authorization: Bearer `. Generate one from the Periskope dashboard under **Settings → API & Webhooks**. API access requires an active Pro or Enterprise plan. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.