> ## 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 > This endpoint is used to send bulk messages to many chats ## OpenAPI ````yaml POST /message/broadcast openapi: 3.0.3 info: title: API - Local description: >- #### Welcome to the official Postman collection of Periskope API Periskope APIs enable you automate actions on your WhatsApp phone, and the Periskope platform - Read more about the APIs & webhooks here - [https://docs.periskope.app/api-reference/introduction](https://docs.periskope.app/api-reference/introduction) - We encourage responsible usage of the APIs. Follow these best practices and recommendations for safe actions on WhatsApp - [https://docs.periskope.app/get-started/best-practices](https://docs.periskope.app/get-started/best-practices) #### Getting Started ##### Pre-requisites: 1. **Sign up for a free account on Periskope:** To use the Periskope API, you need to have an active Periskope account. If you don’t have one, you can sign up for a 7-day free trial [here](https://console.periskope.app). 2. **Scan the QR code from WhatsApp to connect your phone:** A connected phone is required to use the APIs 3. **Go to** [Settings > API](https://console.periskope.app/settings/api), and generate an API key for your organization - The API key is used to authenticate every request. Please keep this secure ##### Using Postman: 1. **Fork the collection so you can edit values and test the APIs in your own postman environment:** To fork the collection, click on the three dots next to v1. Then click on create a fork (_shortcut: Ctrl + Alt + F)._ 2. **Update the value of the variables in the collection:** \- Update the API key with the key generated in Step 3 \- Update the phone number with your connected number. This number will be added to the `x-phone` header across requests It must be in the format of country code+number, with no special characters or spaces _e.g. +91 98745 32456 becomes 919874532456_ For any help or feedback, please contact us at [support@periskope.app](https://mailto:support@periskope.app), or ping us on [WhatsApp](https://what.sapp.link/periskope) version: 1.0.0 contact: {} servers: - url: https://api.periskope.app/v1 security: - bearerAuth: [] tags: - name: contacts - name: tickets - name: tasks - name: phones - name: message - name: queue - name: chats - name: group - name: members - name: webhooks - name: custom properties paths: /message/broadcast: post: tags: - message summary: Broadcast Message description: | This endpoint is used to send bulk messages to many chats operationId: broadcastMessage parameters: - name: x-phone in: header schema: type: string example: '918527184400' description: >- Please provide the number of the phone you want to call with this API in the header. The number must be in country code + number format without any characters or spaces, e.g. 919876543210; Alternatively, provide the phone_id (phone-xxxxxxxxxxxx) in the header requestBody: content: application/json: schema: type: object required: - chat_ids properties: chat_ids: type: array items: type: string description: > - Array of all the recipients - For groups, enter the chat_id of the group. This will be a string that ends with @g.us - For 1-1 chats, enter the country_code + number of the recipient e.g. [919537851844@c.us](https://mailto:919537851844@c.us) (The @c.us is optional) example: 919537851844@c.us message: type: string example: Hello World description: >- - The text body or caption. You can use basic markdown formatting supported by WhatsApp e.g. * for bold, and _ for italic, etc. scheduled_at: type: string example: '2025-02-06T11:21:00Z' description: >- - UTC date and time when the message should be sent, in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ). Example: 2025-02-06T11:21:00Z delay: type: number example: 10 description: >- - Time interval between each broadcasted message in seconds. Defaults to `1 second` media: type: object description: >- - Required to send a media object. You can send a public URL of the media content, or the base64 data of the media - Media can be a document, image, video or audio - `url` - public URL that hosts the content to be sent - `filedata` - Raw bytes of the file, represented in base64 - `type` - The type of the media. Can be image, video, document or audio - `filename` - The filename of the media. Only applicable for document messages poll: type: object description: | - `pollName` - The question or title of the poll - `pollOptions` - Raw bytes of the file, represented in base64 - `options` - Additional options to be sent with the poll - `allowMultipleAnswers` - Boolean. When set to true, respondents can select multiple options - `pollId` - Optional unique identifier of the poll. Useful when sending it across multiple chats reply_to: type: string description: '- To reply to a message, add the message_id in this field' variables: type: array description: >- - Array of variable objects for dynamic message personalization - Each variable can replace placeholders in the message body written in the format `{{var}}` - Note: This parameter is required if `{{var}}` placeholders are present in the message items: type: object properties: values: type: object description: >- Key-value pair of variable names and their values for specific chat_id additionalProperties: type: string example: name: hansal var1: test chat_id: type: string description: The target chat where these values apply example: 91882424xxxx@c.us examples: Broadcast Message: value: chat_id: 919537851844@c.us message: Hello World scheduled_at: '2025-02-06T11:21:00Z' delay: 10 variables: - values: name: admin var1: test chat_id: 919876543210@c.us responses: '200': description: 200 OK headers: Access-Control-Allow-Origin: schema: type: string example: '*' Connection: schema: type: string example: keep-alive Content-Length: schema: type: string example: '70' Date: schema: type: string example: Wed, 22 Jan 2025 10:07:53 GMT ETag: schema: type: string example: W/"46-G83wmhGAIRrmKrMUWfoeGk61n3A" Keep-Alive: schema: type: string example: timeout=5 X-Powered-By: schema: type: string example: Express X-RateLimit-Limit: schema: type: string example: '10' X-RateLimit-Remaining: schema: type: string example: '9' X-RateLimit-Reset: schema: type: string example: '1737540475' x-periskope-org-id: schema: type: string example: 2997dd64-89bf-48d3-9a22-b314fca017e5 x-periskope-phone-id: schema: type: string example: phone-bqzvyibhmwkaergr x-periskope-trace-id: schema: type: string example: bec43610-d8a8-11ef-8033-3b03afb6e098 content: application/json: schema: type: object description: >- The response object contains the `broadcast_id` You can check the status and logs of the broadcast jobs from the `/queue/jobs` endpoint Alternatively, to get all individual message queue jobs for this broadcast, call `POST /message/queues` with `{ "broadcast_id": "" }` in the request body The `broadcast_id` can also be mapped in the message object against the `broadcast_id` (same key) examples: 200 OK: value: broadcast_id: b25192d5-2370-4a69-b844-aae5e2bfae92 hint: >- Track broadcast status: POST /messages/queues with { "broadcast_id": "" } x-codeSamples: - lang: TypeScript label: Node.js source: |- import { PeriskopeApi } from '@periskope/periskope-client'; const client = new PeriskopeApi({ authToken: 'YOUR_API_KEY', phone: 'YOUR_PHONE_NUMBER', // e.g., '919876543210' }); async function broadcastMessage() { const response = await client.message.broadcast({ chat_ids: ['919537851844'], message: 'Hi from Periskope' }); console.log(response); } broadcastMessage(); - lang: cURL label: cURL source: |- curl -X POST \ https://api.periskope.app/v1/message/broadcast \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -H 'x-phone: YOUR_PHONE_NUMBER' \ -d '{ "chat_ids": ["919537851844@c.us"], "message": "Hi from Periskope" }' components: securitySchemes: bearerAuth: type: http scheme: bearer ````