REST API Reference
v1Use the nashir.ai REST API to schedule posts, manage accounts, and integrate with automation tools like n8n and Zapier. All requests must be authenticated with an API key.
https://nashir.ai/api/v1Authentication
All API requests require an API key passed as a Bearer token in the Authorization header. Generate your key from Settings → API Keys. Keys start with up_.
Authorization: Bearer up_your_api_key_hereKeep your key secret
List posts
/api/v1/postsReturns a paginated list of scheduled posts for your team.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| status | string | Filter by status: scheduled, published, partial (live on some accounts, failed on others), failed, draft |
| account_id | string | Filter by platform Page ID (e.g. Facebook page_id like 552126474642948, Instagram user ID, LinkedIn URN). Get IDs from GET /accounts. |
| platform | string | Filter by platform: facebook, instagram, linkedin, tiktok |
| scheduled_from | string | Return posts scheduled after this ISO 8601 datetime |
| scheduled_to | string | Return posts scheduled before this ISO 8601 datetime |
| limit | number | Results per page (default: 20, max: 100) |
| page | number | Page number (default: 1) |
account_id filter
552126474642948 for a Facebook page. No need to look up the internal account ID. Use GET /api/v1/accounts to find Page IDs.curl "https://nashir.ai/api/v1/posts?status=scheduled&account_id=552126474642948&limit=10" \
-H "Authorization: Bearer up_your_api_key_here"Response
{
"data": [
{
"id": 42,
"teamId": 1,
"content": "Excited to announce our new feature! 🚀",
"platforms": ["facebook", "instagram"],
"scheduledAt": "2026-03-25T10:00:00.000Z",
"imageUrl": null,
"status": "scheduled",
"createdAt": "2026-03-22T08:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 1,
"pages": 1
}
}Create a post
/api/v1/postsSchedule a new post. The post will be published automatically at scheduled_at.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| content | string | Yes | Post text (max 2200 chars) |
| platforms | string[] | Yes | Array of platforms: facebook, instagram, linkedin, linkedin_business, tiktok |
| scheduled_at | string | Yes | ISO 8601 datetime (e.g. 2026-03-25T10:00:00Z) |
| image_url | string | No | Public URL of an image to attach |
TikTok — tiktok_options required
tiktok is included in platforms, you must pass a tiktok_options object with at least privacy_level. All interaction flags default to false (disabled) per TikTok guidelines.tiktok_options fields
| Field | Type | Required | Description |
|---|---|---|---|
| privacy_level | string | Yes | PUBLIC_TO_EVERYONE | MUTUAL_FOLLOW_FRIENDS | SELF_ONLY |
| disable_comment | boolean | No | Disable viewer comments. Default: false |
| disable_duet | boolean | No | Disable Duet (video only). Default: false |
| disable_stitch | boolean | No | Disable Stitch (video only). Default: false |
| brand_content_toggle | boolean | No | Enable content disclosure. Default: false |
| brand_organic_toggle | boolean | No | Your Brand (organic) — requires brand_content_toggle: true. Default: false |
| brand_branded_content_toggle | boolean | No | Branded Content / paid partnership — requires brand_content_toggle: true. Default: false |
curl -X POST https://nashir.ai/api/v1/posts \
-H "Authorization: Bearer up_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"content": "Check out our latest blog post! 📖",
"platforms": ["facebook", "instagram", "linkedin", "linkedin_business", "tiktok"],
"scheduled_at": "2026-03-25T10:00:00Z",
"image_url": "https://example.com/blog-cover.jpg",
"tiktok_options": {
"privacy_level": "PUBLIC_TO_EVERYONE",
"disable_comment": false,
"disable_duet": false,
"disable_stitch": false,
"brand_content_toggle": false,
"brand_organic_toggle": false,
"brand_branded_content_toggle": false
}
}'Response 201 Created
{
"data": {
"id": 43,
"teamId": 1,
"content": "Check out our latest blog post! 📖",
"platforms": ["facebook", "instagram"],
"scheduledAt": "2026-03-25T10:00:00.000Z",
"imageUrl": "https://example.com/blog-cover.jpg",
"status": "scheduled",
"createdAt": "2026-03-22T09:00:00.000Z"
}
}Platform notes
Each platform has different content requirements. Make sure your post meets the requirements for every platform you target.
| Platform | Supported content |
|---|---|
| Text, image, video supported | |
| Requires image or video (no text-only posts) | |
| Text and image supported (personal account) | |
| linkedin_business | Text, image, and video supported (organization page) |
| tiktok | Video required (.mp4), no images supported |
TikTok requires a video
Get a post
/api/v1/posts/:idReturns a single post by its ID, enriched with full account details and aggregated analytics. Returns 404 if the post does not exist or belongs to another team.
curl https://nashir.ai/api/v1/posts/42 \
-H "Authorization: Bearer up_your_api_key_here"Response
{
"data": {
"id": 42,
"teamId": 1,
"content": "Excited to announce our new feature! 🚀",
"platforms": ["facebook", "instagram"],
"accountIds": [1, 2],
"scheduledAt": "2026-03-25T10:00:00.000Z",
"imageUrl": null,
"status": "published",
"createdAt": "2026-03-22T08:00:00.000Z",
"accounts": [
{
"id": 1,
"platform": "facebook",
"pageName": "My Business Page",
"pageId": "552126474642948",
"profilePicture": "https://graph.facebook.com/...",
"followerCount": 4200
},
{
"id": 2,
"platform": "instagram",
"pageName": "mybusiness",
"pageId": "987654321",
"profilePicture": null,
"followerCount": null
}
],
"analytics": {
"likes": 128,
"comments": 14,
"shares": 22,
"reach": 3100
}
}
}Delete a post
/api/v1/posts/:idDelete a scheduled post by ID. Returns 204 No Content on success.
curl -X DELETE https://nashir.ai/api/v1/posts/43 \
-H "Authorization: Bearer up_your_api_key_here"List connected accounts
/api/v1/accountsReturns all social media accounts connected to your team.
curl https://nashir.ai/api/v1/accounts \
-H "Authorization: Bearer up_your_api_key_here"Response
{
"data": [
{
"id": 1,
"teamId": 1,
"platform": "facebook",
"pageId": "123456789",
"pageName": "My Business Page",
"profilePicture": "https://graph.facebook.com/...",
"createdAt": "2026-03-01T00:00:00.000Z"
},
{
"id": 2,
"teamId": 1,
"platform": "instagram",
"pageId": "987654321",
"pageName": "mybusiness",
"profilePicture": null,
"createdAt": "2026-03-01T00:00:00.000Z"
},
{
"id": 3,
"teamId": 1,
"platform": "linkedin",
"pageId": "linkedin-personal-123",
"pageName": "John Doe",
"profilePicture": null,
"createdAt": "2026-03-01T00:00:00.000Z"
},
{
"id": 4,
"teamId": 1,
"platform": "linkedin_business",
"pageId": "linkedin-org-456",
"pageName": "My Company",
"profilePicture": null,
"createdAt": "2026-03-01T00:00:00.000Z"
},
{
"id": 5,
"teamId": 1,
"platform": "tiktok",
"pageId": "tiktok-user-789",
"pageName": "@mybusiness",
"profilePicture": null,
"createdAt": "2026-03-01T00:00:00.000Z"
}
]
}Platform Guide
Understanding how each platform works before scheduling posts.
LinkedIn Personal vs Business
LinkedIn Personal (linkedin) and LinkedIn Business (linkedin_business) are two separate connections that never affect each other. You can connect, disconnect, or reconnect one without touching the other.
| Feature | linkedin (Personal) | linkedin_business (Business) |
|---|---|---|
| Posts as | Your personal profile | Your organization page |
| Use case | Thought leadership, personal brand | Company announcements, brand content |
| Supported media | Text, image | Text, image, video |
| Token independence | ✓ Independent | ✓ Independent |
Tip
TikTok notes
Video required
TikTok is currently in sandbox mode — posts are published as private. Public posting becomes available after TikTok app review approval.
Platform support matrix
| Platform | Text only | Image | Video | DMs | Comments |
|---|---|---|---|---|---|
| ✓ | ✓ | ✓ | ✓ | ✓ | |
| ✗ | ✓ | ✓ (Reels) | ✓ | ✓ | |
| LinkedIn Personal | ✓ | ✓ | ✗ | ✗ | ✗ |
| LinkedIn Business | ✓ | ✓ | ✓ | ✗ | ✗ |
| TikTok | ✗ | ✗ | ✓ | ✗ | ✗ |
Register a webhook
/api/v1/webhooksRegister a URL to receive webhook events. nashir.ai will POST to your URL when a post is published. Registering the same URL again updates its event list.
curl -X POST https://nashir.ai/api/v1/webhooks \
-H "Authorization: Bearer up_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.com/webhooks/nashir",
"events": ["post.published"]
}'Response 201 Created
{
"data": {
"id": 1,
"url": "https://your-app.com/webhooks/nashir",
"events": ["post.published"],
"active": true,
"createdAt": "2026-03-22T09:00:00.000Z"
}
}Inbox & Auto-Reply API
Read incoming DMs and comments from your connected Facebook, Instagram and WhatsApp accounts, and send replies — all via API. Ideal for building AI auto-reply workflows in n8n or Zapier. Replying differs by channel: Facebook and Instagram use POST /api/v1/messages/:id/reply (answer a specific message), while WhatsApp uses POST /api/v1/messages (send to a phone number).
List DMs
/api/v1/messagesReturns direct messages received by your connected accounts.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| platform | string | Filter by platform: facebook_dm or instagram_dm |
| is_read | boolean | Filter by read status: true or false |
| account_id | string | Filter by platform Page ID (e.g. 552126474642948). Only returns messages received by that specific page. |
| limit | number | Results per page (default: 20, max: 100) |
| offset | number | Number of results to skip (default: 0) |
curl "https://nashir.ai/api/v1/messages?platform=facebook_dm&account_id=552126474642948&is_read=false" \
-H "Authorization: Bearer up_your_api_key_here"Response
{
"data": [
{
"id": 101,
"team_id": 1,
"platform": "instagram_dm",
"platform_message_id": "mid_AbCdEfGhIjKlMnOp",
"sender_name": "Jane Smith",
"sender_id": "9876543210",
"sender_avatar": null,
"message": "Hi! Do you ship internationally?",
"message_type": "dm",
"created_at": "2026-03-23T14:30:00.000Z",
"is_read": false,
"is_our_reply": false,
"replied_at": null,
"parent_platform_id": null
}
],
"pagination": { "limit": 20, "offset": 0, "total": 1 }
}List comments
/api/v1/commentsReturns comments left on your Facebook posts and Instagram media.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| platform | string | Filter by platform: facebook or instagram |
| is_read | boolean | Filter by read status: true or false |
| account_id | string | Filter by platform Page ID (e.g. 552126474642948). Only returns comments on that specific page. |
| limit | number | Results per page (default: 20, max: 100) |
| offset | number | Number of results to skip (default: 0) |
curl "https://nashir.ai/api/v1/comments?platform=facebook&account_id=552126474642948&is_read=false" \
-H "Authorization: Bearer up_your_api_key_here"Response
{
"data": [
{
"id": 202,
"platform": "instagram",
"platform_message_id": "17858893269000001",
"sender_name": "ahmed_designs",
"sender_id": "ahmed_designs",
"message": "Love this product! Where can I buy it?",
"message_type": "comment",
"created_at": "2026-03-23T10:15:00.000Z",
"is_read": false,
"is_our_reply": false,
"replied_at": null
}
],
"pagination": { "limit": 20, "offset": 0, "total": 1 }
}Reply to a DM
/api/v1/messages/:id/replySend a reply to a direct message. Works for both Facebook Messenger and Instagram DMs. The reply is sent via the Meta Graph API and saved to your inbox automatically. Use the id field from GET /api/v1/messages.
Not for WhatsApp. Passing the id of a WhatsApp message returns 400 with instructions — WhatsApp is keyed by phone number, so use Send a WhatsApp message instead.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| message | string | Yes | The reply text to send |
| pageId | string | No | Facebook/Instagram Page ID to reply from. If omitted, uses the page stored on the message or the first connected account. |
| skip_presentation | boolean | No | true sends the text exactly as given: no product or knowledge lookup and no AI call of any kind for this reply. Default false (nashir may turn a product question into a product list). |
curl -X POST "https://nashir.ai/api/v1/messages/101/reply" \
-H "Authorization: Bearer up_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{ "message": "Yes, we ship worldwide! DM us for details." }'Response
{ "success": true, "message_id": "mid_XyZ123AbC456" }Mark message as read
/api/v1/messages/:id/readMark a specific message as read by its internal ID. Use the id field from GET /api/v1/messages.
curl -X PATCH "https://nashir.ai/api/v1/messages/101/read" \
-H "Authorization: Bearer up_your_api_key_here"Response
{ "success": true, "id": 101 }Send a WhatsApp message
/api/v1/messagesSend a WhatsApp message to a customer from one of your connected WhatsApp numbers. This is the endpoint that delivers — it posts to the WhatsApp Cloud API and saves the message to your inbox. Use it to answer an incoming WhatsApp DM from an n8n or Zapier workflow.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| account_id | number | Yes | Which WhatsApp number to send from — the numeric id from GET /api/v1/accounts (NOT the WhatsApp phone_number_id). |
| to | string | Yes | The customer's phone number in international format, e.g. +9647001234567. |
| message_type | string | No | text (default), image, document, video, or template — see "Send a document or a video" and "Send a WhatsApp template to one number" below. |
| content | string | Yes* | The message text. Required when message_type is text. For document and video it is an optional caption. |
| image_url | string | Yes* | Public JPEG/PNG URL. Required when message_type is image (WhatsApp rejects WebP for images). |
| document_url | string | Yes* | Public https URL of the file (for example a PDF). Required when message_type is document. |
| filename | string | No | The file name the customer sees for a document, e.g. company-profile.pdf. |
| video_url | string | Yes* | Public https URL of an MP4 video. Required when message_type is video. |
| dry_run | boolean | No | true = PREVIEW ONLY. Every check runs and the answer is 200 with "dry_run": true and a "preview" object — NOTHING IS SENT. Leave it out to send. |
| nashir_message_id | number | No | The inbox id of the message you are answering, so the reply threads to it. |
| skip_presentation | boolean | No | true sends the text exactly as given: no product or knowledge lookup and no AI call of any kind for this send. Default false — nashir may rewrite a text answer to a product question into a product list. Use true when your own bot writes the final answer. |
| idempotency_key | string | No | Up to 255 characters, unique per message. A repeat within 24 hours returns the first answer and never sends twice. See Idempotency below. |
curl -X POST "https://nashir.ai/api/v1/messages" \
-H "Authorization: Bearer up_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"account_id": 900000101,
"to": "+9647001234567",
"message_type": "text",
"content": "Yes, we ship worldwide! What city are you in?"
}'Response
{
"id": 900000002,
"message_id": "wamid.HBgLXXXXXXXXXXXXFQIAERgSXXXXXXXX...",
"wamid": "wamid.HBgLXXXXXXXXXXXXFQIAERgSXXXXXXXX...",
"status": "sent",
"created_at": "2026-08-05T09:43:39.165Z"
}Behaviour to build around
| Case | You get | What it means |
|---|---|---|
| Sent | 201 + message_id | WhatsApp accepted it and it is in your inbox. Delivery is reported later: GET /api/v1/messages/{id}, or the message.delivered / message.read / message.failed webhooks. |
| Duplicate suppressed | 200, no message_id | The same text to the same recipient arrived twice in quick succession; nothing was sent. This protects your customer from a retrying workflow — check for message_id, not just a 2xx. |
| Outside the 24h window | 409 outside_window | WhatsApp only allows free-form messages for 24 hours after the customer's last message to this number. Past that, nothing is sent and you get outside_window: send an approved template instead (message_type "template"). WhatsApp itself does not refuse such a message at once — it accepts it and drops it seconds later — so if that ever happens it arrives as message.failed with code outside_window. |
| No WhatsApp on the plan | 403 plan_required | WhatsApp is a paid feature, or (whatsapp_number_blocked) the number is currently blocked from sending. |
| Wrong account_id | 404 account_not_found | That id is not an active WhatsApp account on your team — list them with GET /api/v1/accounts. |
| WhatsApp refused it | 422 meta_rejected (or a specific code) | meta_code and meta_message carry WhatsApp’s answer. The full list of codes is under "Send a WhatsApp template to one number" → Errors. |
Note: nashir applies outbound guardrails to content and, for catalog-style questions, may substitute a server-composed product answer — so the delivered text can differ slightly from what you posted. The message saved to your inbox is always exactly what the customer received. A normal send does not take the chat. If a person is sending, add "sender": "staff". If a person holds the chat, a bot send gets a 409: see Chat control for external bots.
Send a document or a video
The same endpoint sends a file (for example a PDF) or an MP4 video by link. WhatsApp fetches the link itself, so it must be a public https URL that needs no login. These are free-form messages: like text, they are only allowed inside the 24-hour window, and outside it you get 409 outside_window. To send a document to someone outside the window, use an approved template with a document header instead.
curl -X POST "https://nashir.ai/api/v1/messages" \
-H "Authorization: Bearer up_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"account_id": 900000101,
"to": "+9647001234567",
"message_type": "document",
"document_url": "https://example.com/files/company-profile.pdf",
"filename": "company-profile.pdf",
"content": "Here is our company profile."
}'For a video, send "message_type": "video" with video_url instead of document_url and filename. A successful send answers 201 with a message_id, exactly like a text.
| Case | You get | What it means |
|---|---|---|
| Documents and videos are not enabled for your team | 403 inbox_media_not_enabled | Nothing is sent. The answer says so in message and message_ar; it is never a silent success. Ask nashir support to enable it for your team. |
| The link is missing or is not https | 400 invalid_request | document_url or video_url must be a public https URL. |
| Outside the 24h window | 409 outside_window | Nothing is sent. Use an approved template (a template can carry a document or video header). |
| "dry_run": true | 200 + "dry_run": true | A preview only — nothing is sent and there is no message_id. |
Show typing on WhatsApp
Shows WhatsApp’s “typing…” indicator to a customer while your own workflow (your n8n, your server) prepares its reply. Call it as soon as a message.received webhook arrives, then send the reply with POST /api/v1/messages.
/api/v1/messages/typing| Field | Required | Meaning |
|---|---|---|
account_id | Yes | The WhatsApp number the customer wrote to: social_account_id in the message.received webhook, or the id from GET /api/v1/accounts. |
message_id | Yes, or nashir_message_id | The WhatsApp message id from the message.received webhook (message_id). |
nashir_message_id | Instead of message_id | The message’s id in your nashir inbox. |
POST /api/v1/messages/typing
Authorization: Bearer up_your_key_here
Content-Type: application/json
{
"account_id": 900000501,
"message_id": "wamid.HBgMOTY0NzcwMDAwMDAwFQIAEhgURVhBTVBMRV9UWVBJTkdfMDAwMQA="
}HTTP/1.1 200 OK
{
"ok": true,
"expires_in_seconds": 25,
"message_id": "wamid.HBgMOTY0NzcwMDAwMDAwFQIAEhgURVhBTVBMRV9UWVBJTkdfMDAwMQA=",
"nashir_message_id": 900000601
}Four rules
- It marks the message read. WhatsApp shows typing only together with the blue ticks, on that message and every earlier one in the chat.
- It lasts up to 25 seconds, or until you reply, whichever comes first.
- Use it only if you will reply. A customer who sees typing and then gets nothing is left waiting.
- If your workflow takes longer than 25 seconds, call it again. A repeat for the same message within 5 seconds sends nothing new to WhatsApp: it answers ok with the seconds left and "repeated": true.
{ "ok": true, "expires_in_seconds": 22, "repeated": true, … }The message must be one the customer sent to that number in your team. If a person on your team has taken over the chat, the call is refused, exactly like a bot reply would be. A person typing through your own tool can pass "sender": "staff", as with POST /api/v1/messages. Nothing is added to your inbox.
| code | HTTP | Meaning |
|---|---|---|
invalid_request | 400 | account_id or message_id is missing or not valid. |
account_not_found | 404 | That WhatsApp number is not connected to your team, or its connection has expired. |
message_not_found | 404 | No message with that id on this number in your team. |
not_inbound | 422 | The message was sent by your team, not by the customer. |
chat_controlled | 409 | A person on your team holds the chat. control says who and until when. |
whatsapp_not_on_plan | 403 | WhatsApp is not included in your current plan. |
subscription_expired | 403 | Your subscription has expired. |
forbidden | 403 | This API key may not reply on this number. |
meta_rejected | 422 | WhatsApp refused. meta_code and meta_message carry WhatsApp’s own reason (for example a message id older than 30 days). |
account_reconnect_required | 422 | The number’s connection has expired. Reconnect it in Channels. |
meta_rate_limited | 429 | WhatsApp is limiting this number. Wait and try again. |
whatsapp_unreachable | 503 | We could not reach WhatsApp, so typing was not shown. Try again. |
HTTP/1.1 409 Conflict
{
"code": "chat_controlled",
"message": "A person on the team is handling this chat, so the bot cannot show typing.",
"message_ar": "أحد أعضاء الفريق يتولى هذه المحادثة، لذلك لا يمكن للبوت إظهار مؤشر الكتابة.",
"control": { "owner": "human", "since": "…", "until": null, "reason": "staff_takeover" }
}In the n8n community node: Nashir WhatsApp → Show Typing (version 0.19.0 and later). It takes the message id from the incoming webhook item by default.
Reply to a comment
/api/v1/comments/:id/replyPost a reply to a Facebook or Instagram comment. Replies appear nested under the original comment on the platform and are saved to your inbox. Use the id field from GET /api/v1/comments.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| message | string | Yes | The reply text to post |
| pageId | string | No | Facebook/Instagram Page ID to reply from. If omitted, uses the page stored on the comment or the first connected account. |
curl -X POST "https://nashir.ai/api/v1/comments/202/reply" \
-H "Authorization: Bearer up_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{ "message": "Thank you! You can order at our website link in bio." }'Response
{ "success": true, "comment_id": "17858893269000999" }Chat control for external bots
A chat is answered either by your bot or by a person on your team. Nashir keeps one record of who holds each chat. Use this section if your own bot (for example in n8n) answers your customers.
The forward payload
A message.received webhook fires for WhatsApp messages. You still receive the message while a person holds the chat, so your bot keeps the context. The three fields below are inside data.
| Field | Meaning |
|---|---|
control.owner | bot: your bot may answer. human: do not answer. |
control.since | When the hold started. null when there is no hold. |
control.until | When the hold ends by itself. null means no set end. |
control.reason | Why the chat is held, for example manual_pause, agent_replied, staff_takeover or handoff. |
social_account_id | The WhatsApp number that received the message. Send it as account_id in your API calls. |
recent_turns | Up to 20 recent messages of this chat on this number, oldest first. Each has speaker (customer, staff or bot), text (up to 1,000 characters) and at. |
{
"event": "message.received",
"team_id": 9999,
"data": {
"channel": "whatsapp",
"phone": "9647001234567",
"sender_key": "9647001234567",
"bsuid": null,
"username": null,
"message_id": "wamid.xxx",
"content": "Is this still available?",
"media_type": null,
"media_id": null,
"media_url": null,
"control": {
"owner": "human",
"since": "2026-11-02T13:05:33.431+00:00",
"until": "2026-11-02T15:05:33.431+00:00",
"reason": "agent_replied"
},
"social_account_id": 1234,
"recent_turns": [
{ "speaker": "customer", "text": "Hello", "at": "2026-11-02T13:04:10.000+00:00" },
{ "speaker": "bot", "text": "Welcome! How can I help?", "at": "2026-11-02T13:04:15.000+00:00" },
{ "speaker": "staff", "text": "Yes, we have it in stock.", "at": "2026-11-02T13:05:33.000+00:00" }
],
"referral": null,
"timestamp": 1793624733
}
}The 409 refusal
If a person holds the chat when your bot sends, nashir refuses the send and nothing reaches the customer. This covers POST /api/v1/messages, POST /api/v1/messages/:id/reply, POST /api/v1/comments/:id/reply and POST /api/v1/comments/:id/private-reply. A 409 is the correct result, so do not retry it.
HTTP 409
{
"error": "A person on the team is handling this chat, so the bot reply was not sent.",
"code": "chat_controlled_by_human",
"control": {
"owner": "human",
"since": "2026-11-02T13:05:23.794+00:00",
"until": null,
"reason": "manual_pause"
}
}Refused reasons: agent_replied, agent_replied_from_phone, agent_replied_from_web, agent_replied_from_meta, manual_pause, owner_takeover, staff_takeover, and handoff after 2 minutes (at once on a comment).
In n8n
- Right after the Webhook node, add an IF node that continues only when
{{ $json.body.data.control.owner }}equalsbot. This saves the AI call when a person holds the chat. - A person can step in while the bot is writing, so handle the 409 too. On the node that sends the reply, set On Error to continue, so a 409 does not fail the run.
- End that branch when the response has
codechat_controlled_by_human. Do not send the reply again.
The control API
Read or change who holds a chat, on any channel: GET and POST /api/v1/conversations/control.
| Field | Meaning |
|---|---|
platform | whatsapp, facebook_dm, facebook_comment, instagram_dm, instagram_comment, website_chat, tiktok_dm or tiktok_comment. |
key | The chat. On WhatsApp, use phone from the forward payload. |
account_id | Which WhatsApp number. Use social_account_id from the forward payload. |
action | POST only: take or release. |
timeout_seconds | Optional, on take: 60 to 86400. The hold ends by itself. Without it, the hold lasts until released, up to the maximum set for the business. |
reason | Optional, on take: manual_pause (default), agent_replied or staff_takeover. |
# Read
curl "https://nashir.ai/api/v1/conversations/control?platform=whatsapp&key=9647001234567&account_id=1234" \
-H "Authorization: Bearer up_your_api_key_here"
# Take for one hour
curl -X POST "https://nashir.ai/api/v1/conversations/control" \
-H "Authorization: Bearer up_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{ "platform": "whatsapp", "key": "9647001234567", "account_id": 1234, "action": "take", "timeout_seconds": 3600 }'
# Give it back
curl -X POST "https://nashir.ai/api/v1/conversations/control" \
-H "Authorization: Bearer up_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{ "platform": "whatsapp", "key": "9647001234567", "account_id": 1234, "action": "release" }'
# Response of all three
{ "owner": "human", "since": "2026-11-02T13:05:19.403+00:00", "until": "2026-11-02T14:05:19.403+00:00", "reason": "manual_pause", "replies_held": true }| Status | Meaning |
|---|---|
200 | Done. The body is the chat’s current state. |
400 | A field is wrong. The error says which. |
403 | This key may not reply on that business. |
404 | POST only: this chat has no messages, so no hold was created. Check key and account_id. |
sender: "staff"
A send with your API key counts as your bot. If a person is typing through your own tool, add "sender": "staff" on POST /api/v1/messages or POST /api/v1/messages/:id/reply. The send goes through even during a hold, and a successful send holds the chat for 2 hours with reason agent_replied. Never set it on messages your bot writes.
curl -X POST "https://nashir.ai/api/v1/messages" \
-H "Authorization: Bearer up_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{ "account_id": 1234, "to": "9647001234567", "message_type": "text", "content": "Hi, this is Sara from the team.", "sender": "staff" }'control.changed
Sent whenever a chat changes hands, whoever caused it: the inbox, the WhatsApp Business app, Meta’s inbox, or the API. Expiries can arrive up to 15 minutes late. A refused send does not fire it.
{
"event": "control.changed",
"team_id": 9999,
"data": {
"platform": "whatsapp",
"conversation_key": "9647001234567",
"social_account_id": 1234,
"change": "take",
"owner": "human",
"reason": "agent_replied",
"until": "2026-11-02T15:05:33.431Z",
"actor": "staff",
"at": "2026-11-02T13:05:33.500Z"
}
}| Field | Meaning |
|---|---|
change | take, renew, release or expire. |
owner | Who holds the chat after this change: human or bot. |
actor | Who caused it: staff, phone_app, meta_app, web_app, api, bot, system or mcp. |
When until moves: on WhatsApp, Facebook, Instagram, TikTok DMs and web chat, each customer message during a timed hold moves until to 2 hours after that message, if it was earlier. This includes a hold you set with timeout_seconds. It fires renew with actor system. Another staff reply also moves it and fires renew. A hold with until set to null stays open-ended, and a hold that has already ended does not come back.
A release no person pressed: you may get change release with actor system and reason private_reply_awaiting_user. The chat was waiting for the customer to answer a private reply to their comment, and they just did. Nobody on the team handed the chat back.
To subscribe: open Settings → Developer → Webhooks, press Edit events on your webhook, tick Chat control changed, and save. Or press Add Webhook for a separate one. Each webhook has its own secret, so check each signature with its own secret.
Facebook and Instagram DMs
Your bot can answer Facebook and Instagram direct messages too. Each channel has its own event, and you choose: message.received.facebook and message.received.instagram. A message.received webhook does not receive them. Comments are not forwarded.
| Field | Meaning |
|---|---|
channel | facebook or instagram. |
sender_id | The customer. Use it as key in the control API. |
sender_name | The customer’s name, when Meta gives it. |
page_id | The Page or Instagram account that received the message. |
nashir_message_id | The id to reply to. Use it as :id in the reply route. |
message_id | Meta’s id for the message. |
content, media_type, media_url | The message. |
control, social_account_id, recent_turns | The same as on WhatsApp, above. |
{
"event": "message.received.instagram",
"team_id": 9999,
"data": {
"channel": "instagram",
"sender_id": "17841400000000000",
"sender_name": "Sara",
"page_id": "17841411111111111",
"nashir_message_id": 27400000,
"message_id": "aWdfZAG1faXRlbToxOk...",
"content": "Is this still available?",
"media_type": null,
"media_url": null,
"control": { "owner": "bot", "since": null, "until": null, "reason": null },
"social_account_id": 1234,
"recent_turns": [
{ "speaker": "customer", "text": "Is this still available?", "at": "2026-11-02T13:04:10.000+00:00" }
],
"timestamp": 1793624733
}
}Always reply through nashir’s API, never with your own Meta token. Meta tells us about every message your Page sends. A reply sent with another token looks like a person on your team, so the chat is held and your bot stops itself. It also skips the 409 check.
curl -X POST "https://nashir.ai/api/v1/messages/27400000/reply" \
-H "Authorization: Bearer up_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{ "message": "Yes, we have it in stock." }'
# Response
{ "success": true, "message_id": "aWdfZAG1faXRlbToxOk...", "image_message_id": null }| You get | Meaning |
|---|---|
200 | Sent. |
409 chat_controlled_by_human | A person holds the chat. Do not retry. |
424 outside_messaging_window | Meta refused: the customer’s last message is over 24 hours old (last_customer_message_at). Wait for the customer to write again. |
424 another_app_holds_thread | Another app controls this conversation on Meta, such as Meta Business AI. Check Conversation Routing in the Page’s settings. |
424 | Any other refusal from Meta. The error carries Meta’s message. |
Meta’s standard messaging window is 24 hours from the customer’s last message, and up to 7 days after a first message from a Click-to-Messenger or Click-to-Direct ad. A bot can’t reply outside it. The Human Agent tag is for people only, so nashir never adds it to a bot’s message. Staff can reply from the nashir inbox.
If a nashir bot already answers on that channel, turn one of them off. Otherwise customers get two replies.
ai-status, pause and ai-toggle
These endpoints keep working. For new work, use the forward’s control field and the control API. The POST endpoints return 404 when the chat has no messages, and write no hold. A resume still works on a chat that has a hold.
| Endpoint | Send | Returns |
|---|---|---|
GET /api/v1/conversations/ai-status | Query: platform, key, optional account_id. | ai_enabled, paused_since, paused_by, reason, auto_resumes_at. On a held comment, ai_enabled is true with replies_held: true: moderation may run, but replies are refused. |
GET /api/v1/conversations/:phone/ai-status | WhatsApp, older form. | The same five fields. |
POST /api/v1/conversations/pause | platform, conversation_key, duration_seconds (60 to 86400), optional reason (default handoff), account_id, phone, handoff_reason, handoff_details. | ok, platform, conversation_key, paused_until, duration_seconds. |
POST /api/v1/ai/pause | WhatsApp, older form: phone, duration_seconds (60 to 86400), optional reason (default handoff). | ok, phone, paused_until, duration_seconds. |
POST /api/v1/conversations/:phone/ai-toggle | WhatsApp: action (pause or resume), optional reason. A pause has no end time. Teams with 2 or more numbers get a 400: use the control API. | success, action, phone. |
{
"ai_enabled": false,
"paused_since": "2026-11-02T13:05:23.794+00:00",
"paused_by": null,
"reason": "manual_pause",
"auto_resumes_at": null
}Send a WhatsApp template to one number
WhatsApp allows a free-form message only within 24 hours of the customer’s last message to your number. To reach anyone outside that window, such as a renewal reminder, an order update or an appointment confirmation, send an approved template. It works for any number, not only customers who already wrote to you. The message is added to that customer’s conversation in your inbox as a message from your team.
Who pays: Meta charges each template to your own WhatsApp Business account at its published rates. nashir adds no charge per message.
Who is refused: the same rule as a template sent from your inbox. A contact who opted out, is on your never-message list, is marked do not contact, or is archived is never sent a template. A recorded opt-in is not required, but WhatsApp’s policy still requires that the person agreed to hear from you.
1. List the templates a number can send
/api/v1/whatsapp/templates?account_id={id}Returns the approved templates of that WhatsApp number with what each one needs: the number of body variables, header variables, and link buttons that take a value per send (their index). account_id is optional when your team has one WhatsApp number. sendable is false for templates this endpoint cannot send (authentication templates, which go through POST /api/v1/otp/send, and templates with named variables such as {{name}}).
curl "https://nashir.ai/api/v1/whatsapp/templates?account_id=900000101" \
-H "Authorization: Bearer up_your_api_key_here"
{
"account_id": 900000101,
"data": [
{
"id": 900000201,
"name": "renewal_reminder",
"language": "ar",
"category": "UTILITY",
"status": "approved",
"sendable": true,
"variables": { "body": 2, "header": 0, "buttons": ["0"] },
"header_type": "none",
"body_text": "مرحباً {{1}}، ينتهي اشتراكك في {{2}}. اضغط الزر للتجديد.",
"footer_text": null
}
]
}2. Send it
/api/v1/messages| Field | Required | Meaning |
|---|---|---|
account_id | Yes | The WhatsApp number that sends it (the id from GET /api/v1/accounts). |
to | Yes | The customer’s number in international format, e.g. +9647001234567. |
message_type | Yes | "template". |
template | Yes | { "name": "…", "language": "ar" } or { "id": 900000201 }. The template must exist on this number and be approved. The id is the nashir template id — see “Where to find the template id” below. |
variables | If the body has {{1}}… | Body values, in order: ["Ali", "2026-12-15"] or {"1": "Ali", "2": "2026-12-15"}. |
header_variables | If the header has {{1}} | Same shape, for a text header. |
button_variables | If a link button takes a value | The end of the link per button index: {"0": "INV-20931"}. For a carousel card: {"card_0_1": "…"}. |
header_media_url | No | A public https link to use as the image, video or document header for this send instead of the template’s own. |
idempotency_key | No | See Idempotency below. Strongly recommended. |
dry_run | No | Leave it out to send. true = PREVIEW ONLY: every check runs and the filled-in text comes back, but NOTHING IS SENT. See the warning below. |
curl -X POST "https://nashir.ai/api/v1/messages" \
-H "Authorization: Bearer up_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"account_id": 900000101,
"to": "+9647001234567",
"message_type": "template",
"template": { "name": "renewal_reminder", "language": "ar" },
"variables": { "1": "Ali", "2": "2026-12-15" },
"button_variables": { "0": "INV-20931" },
"idempotency_key": "renewal-inv-1"
}'
HTTP 201
{
"id": 900000301,
"message_id": "wamid.HBgLOTY0NzAwMTIzNDU2NxUCABEYEjY...",
"wamid": "wamid.HBgLOTY0NzAwMTIzNDU2NxUCABEYEjY...",
"status": "sent",
"created_at": "2026-11-12T09:30:11.204Z",
"template": { "id": 900000201, "name": "renewal_reminder", "language": "ar", "category": "UTILITY" }
}Values cannot be empty and cannot contain line breaks, tabs or 4 spaces in a row (WhatsApp refuses them). The count is checked against the template before anything is sent: body, header and each link button.
dry_run: true sends NOTHING
With "dry_run": true the request is only checked. The answer is HTTP 200 (not 201), it carries "dry_run": true and a "preview" object, and it has no message_id or wamid. No message reaches the customer and nothing appears in your inbox. A workflow that reports success on any 2xx will look as if it sent. To send for real, remove the field (or set it to false) and check for status "sent" and a message_id.
curl -X POST "https://nashir.ai/api/v1/messages" \
-H "Authorization: Bearer up_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"account_id": 900000101,
"to": "+9647001234567",
"message_type": "template",
"template": { "id": 900000201 },
"variables": ["Ali", "2026-12-15"],
"button_variables": { "0": "INV-20931" },
"dry_run": true
}'
HTTP 200 <-- not 201: NOTHING WAS SENT
{
"dry_run": true,
"preview": {
"account_id": 900000101,
"business_id": null,
"to": "9647001234567",
"message_type": "template",
"template": { "id": 900000201, "name": "renewal_reminder", "language": "ar", "category": "UTILITY" },
"text": "...the filled-in message...",
"components": [ ... ]
}
}Where to find the template id
template.id is the nashir template id, not Meta’s template id. Two ways to get it: (1) in the dashboard, open WhatsApp → Templates — every template card shows a small “ID …” chip, and clicking it copies the number; (2) call GET /api/v1/whatsapp/templates (step 1 above) and read "id". Sending by name and language works too and needs no id.
Sending a carousel template
An approved carousel template is sent the same way. The card images, captions and buttons are the ones approved with the template. The only per-send values are the message body variables (variables) and, for a card whose link button ends in {{1}}, the end of that link: button_variables with the key card_<card>_<button>, both counted from 0. So "card_0_1" is the second button of the first card. GET /api/v1/whatsapp/templates lists the exact keys a template needs under variables.buttons.
curl -X POST "https://nashir.ai/api/v1/messages" \
-H "Authorization: Bearer up_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"account_id": 900000101,
"to": "+9647001234567",
"message_type": "template",
"template": { "id": 900000202 },
"variables": ["Ali"],
"button_variables": {
"card_0_1": "summer-offer",
"card_1_1": "winter-offer"
},
"idempotency_key": "offers-dec-1"
}'Known limit: variables inside a card’s own caption cannot be filled through this endpoint yet. A carousel template whose card captions contain {{1}} cannot be sent from here; use fixed card captions.
3. Errors
Every error of POST /api/v1/messages is JSON with code, message and message_ar (error repeats message, for older integrations). Branch on code. No error is ever 502 or 504.
| Status | code | Meaning |
|---|---|---|
400 | invalid_request | A field is missing or malformed. message says which. |
404 | account_not_found | account_id is not an active WhatsApp number of your team. |
404 | template_not_found | No such template on this number. available_languages lists the languages that exist for that name. |
422 | template_not_approved | The template is pending, rejected or paused. |
422 | template_not_supported | Authentication template, or named variables. |
422 | variable_count_mismatch | Wrong number of values. expected and got show where. |
403 | recipient_opted_out | The contact opted out (in nashir or in WhatsApp). |
403 | recipient_blocked | Never-message list, do not contact, or archived. reason says which. |
422 | recipient_not_on_whatsapp | WhatsApp could not deliver to this number (Meta 131026). |
402 | waba_payment_issue | Your WhatsApp Business account has no valid payment method in Meta. |
422 | account_reconnect_required | The WhatsApp number’s connection expired (Meta 190). Reconnect it in Channels. |
409 | outside_window | Only for text, image, document, video and options: the 24-hour window is closed. Send a template. |
422 | meta_rejected | Any other refusal by WhatsApp. meta_code and meta_message carry Meta’s answer. |
429 | meta_rate_limited | WhatsApp is slowing this number down. Retry later with the same idempotency_key. |
403 | trial_limit_reached | The trial’s template allowance is used up. |
403 | plan_required · subscription_expired · forbidden · whatsapp_number_blocked | Plan, key permission or number health. |
503 | whatsapp_unreachable · consent_check_unavailable | Temporary. Retry with the same idempotency_key. |
HTTP 422
{
"error": "The number of variables does not match the template (variables: expected 2, got 1).",
"code": "variable_count_mismatch",
"message": "The number of variables does not match the template (variables: expected 2, got 1).",
"message_ar": "عدد المتغيرات لا يطابق القالب (variables: المتوقع 2، المُرسل 1).",
"expected": { "body": 2, "header": 0, "buttons": ["0"] },
"got": { "body": 1, "header": 0, "buttons": ["0"] }
}Idempotency
Add idempotency_key (any text up to 255 characters, unique per message) to any POST /api/v1/messages, not only templates. For 24 hours, repeating the same request with the same key returns the original answer, with the header Idempotent-Replayed: true, and never sends again. So a timeout or a retry in your workflow cannot message a customer twice.
| Case | You get |
|---|---|
| Same key, same request, within 24 hours | The original response, replayed. Nothing is sent. |
| Same key, different request | 422 idempotency_key_reused. |
| Same key while the first is still running | 409 idempotency_in_progress. Retry in a few seconds. |
| The first was refused before reaching WhatsApp (400, 403, 404…) | The key is free again: fix the request and retry with it. |
nashir_message_id keeps its meaning: the inbox id of the message you are answering, used to thread the reply. It is not an idempotency key.
Delivery status
A 201 means WhatsApp accepted the message, not that it arrived. WhatsApp reports delivery a few seconds later. Follow it in either of two ways, for every message sent through POST /api/v1/messages (text, media, options and templates):
/api/v1/messages/{id}{id} is the id returned by the send (a wamid works too). status is sent, delivered, read or failed; a failed message carries error with the same code as above, Meta’s code and a plain reason in English and Arabic.
curl "https://nashir.ai/api/v1/messages/900000301" \
-H "Authorization: Bearer up_your_api_key_here"
{
"id": 900000301,
"message_id": "wamid.HBgLOTY0...",
"wamid": "wamid.HBgLOTY0...",
"platform": "whatsapp",
"direction": "outbound",
"phone": "9647001234567",
"type": "dm",
"content": "مرحباً Ali، ينتهي اشتراكك في 2026-12-15. اضغط الزر للتجديد.",
"status": "failed",
"sent_at": "2026-11-12T09:30:12.000Z",
"delivered_at": null,
"read_at": null,
"failed_at": "2026-11-12T09:30:14.000Z",
"error": {
"code": "recipient_not_on_whatsapp",
"meta_code": 131026,
"reason": "WhatsApp couldn’t deliver this message and doesn’t say why. ...",
"reason_ar": "لم يتمكن واتساب من إيصال هذه الرسالة ولا يوضّح السبب. ...",
"message": "WhatsApp could not deliver to this number. ...",
"message_ar": "تعذّر على واتساب الإيصال إلى هذا الرقم. ..."
}
}Or subscribe your webhook (Settings → Developer → Webhooks) to message.delivered, message.read and message.failed. A text sent outside the 24-hour window that WhatsApp accepted and then dropped arrives here as message.failed with code outside_window.
POST <your webhook URL>
X-Nashir-Event: message.failed
X-Nashir-Signature: sha256=...
{
"event": "message.failed",
"team_id": 900000401,
"data": {
"id": 900000302,
"message_id": "wamid.HBgLOTY0...",
"phone": "9647001234567",
"account_id": 900000101,
"message_type": "text",
"status": "failed",
"timestamp": "2026-11-12T09:41:07.000Z",
"error": {
"code": "outside_window",
"meta_code": 131047,
"reason": "More than 24 hours have passed since this contact last replied, so WhatsApp requires an approved template to reach them again.",
"reason_ar": "مضى أكثر من 24 ساعة منذ آخر رد من جهة الاتصال هذه، لذلك يشترط واتساب استخدام قالب معتمد للتواصل معها من جديد.",
"message": "...",
"message_ar": "..."
}
}
}Example: renewal reminders
Create and get approval for a UTILITY template first (WhatsApp → Templates), for example: «مرحباً {{1}}، ينتهي اشتراكك في {{2}}. اضغط الزر للتجديد.» with a “Renew” link button ending in {{1}}. Then, from your own system:
// Daily job in your system: remind every customer whose plan ends in 3 days.
for (const sub of await subscriptionsEndingIn(3)) {
const res = await fetch('https://nashir.ai/api/v1/messages', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.NASHIR_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
account_id: 900000101,
to: sub.phone,
message_type: 'template',
template: { name: 'renewal_reminder', language: 'ar' },
variables: [sub.customerName, sub.endDate], // {{1}}, {{2}}
button_variables: { '0': sub.invoiceId }, // the "Renew" link suffix
idempotency_key: 'renewal-' + sub.invoiceId, // a retry never sends twice
}),
});
const body = await res.json();
if (res.status === 201) await saveMessageId(sub.id, body.id); // follow it later
else if (body.code === 'recipient_opted_out' || body.code === 'recipient_blocked') await markDoNotRemind(sub.id);
else if (res.status === 429 || res.status === 503) await retryLater(sub.id); // same idempotency_key
else console.error(body.code, body.message);
}
// Then: subscribe to message.delivered / message.read / message.failed
// (Settings → Developer → Webhooks), or poll GET /api/v1/messages/{id}.Create a WhatsApp broadcast
/api/v1/broadcastsSend an approved WhatsApp template to your contacts now, or schedule it. Contacts who opted out, are on your never-message list, or are archived are never messaged. Pass dry_run: true to get the exact recipient count without creating anything.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Campaign name |
| templateId | number | Yes | Id of one of your WhatsApp templates |
| contactFilter | object | No | Who receives it, e.g. {"type":"all"} (default) or {"type":"tag","tag":"vip"} |
| variableValues | object | No | Values for the template variables: {"1":"Ali","2":"20"} |
| scheduledAt | string | No | When to send — see "Scheduling time" below. Omit to send now. |
| socialAccountId | number | If 2+ numbers | Which WhatsApp number sends it |
| dry_run | boolean | No | true = preview only, nothing is created |
Scheduling time
scheduledAt is an ISO 8601 date and time. How it is read depends on whether it carries a time zone:
| You send | It means |
|---|---|
| 2026-10-20T15:30 | No zone: YOUR business's local time. For a business in Baghdad this sends at 15:30 Baghdad time (12:30 UTC). |
| 2026-10-20T15:30+03:00 | An explicit offset is honoured exactly: 15:30 at UTC+3 (12:30 UTC). |
| 2026-10-20T12:30:00Z | Z means UTC: 12:30 UTC. |
Which local time?
timezone_unknown — it is never guessed. Set your time zone in Settings → Team, or send the time with an offset or Z.Scheduling errors
| Status | code | When |
|---|---|---|
| 400 | invalid_scheduled_at | Not an ISO 8601 date and time (e.g. "tomorrow", "20/10/2026 15:30") |
| 400 | scheduled_in_past | The time has already passed (2 minutes of clock skew are allowed) |
| 409 | timezone_unknown | No zone in the value and no business / team time zone or single-zone country to read it in |
curl -X POST https://nashir.ai/api/v1/broadcasts \
-H "Authorization: Bearer up_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Eid offer",
"templateId": 900000201,
"contactFilter": { "type": "tag", "tag": "vip" },
"variableValues": { "1": "20%" },
"scheduledAt": "2026-10-20T15:30"
}'Response 202 Accepted
{
"id": 912,
"status": "scheduled",
"scheduledAt": "2026-10-20T12:30:00.000Z",
"scheduledAtTimezone": "Asia/Baghdad",
"recipientCount": 340,
"enqueued": true
}scheduledAt in every response is UTC (it ends in Z). scheduledAtTimezone is the zone a value without a zone was read in. The list endpoint GET /api/v1/broadcasts returns scheduledAt, sentAt and createdAt in UTC too.
n8n & Zapier integration
nashir.ai works with any HTTP-based automation tool. Here's how to connect from n8n.
n8n — Schedule posts
Use the HTTP Request node with these settings to schedule a post from any n8n workflow:
# n8n HTTP Request node configuration
Method: POST
URL: https://nashir.ai/api/v1/posts
Auth type: Header Auth
Header name: Authorization
Header val: Bearer up_your_api_key_here
# Body (JSON)
{
"content": "{{ $json.caption }}",
"platforms": ["facebook", "instagram", "linkedin", "linkedin_business", "tiktok"],
"scheduled_at": "{{ $json.publish_date }}",
"image_url": "{{ $json.image_url }}"
}Zapier — Webhooks by Zapier
In Zapier, use the Webhooks by Zapier action and set:
Action: POST
URL: https://nashir.ai/api/v1/posts
Headers: Authorization: Bearer up_your_api_key_here
Content-Type: application/json
Data: content → (your caption field)
platforms → ["facebook"]
scheduled_at → (your date field, ISO 8601)n8n auto-reply workflow
Build a fully automated DM responder in n8n. The workflow polls for unread messages, generates a reply with AI, and sends it — all without human intervention.
Trigger — Schedule node
Runs every 5 minutes (or use a Webhook trigger for real-time response).
# Schedule node
Interval: Every 5 minutesHTTP Request — Fetch unread DMs
Fetches all unread Instagram DMs for your team.
Method: GET
URL: https://nashir.ai/api/v1/messages?platform=instagram_dm&is_read=false&limit=10
Headers: Authorization: Bearer up_your_api_key_hereIF node — Check for new messages
Only continue if the response contains at least one message.
Condition: {{ $json.pagination.total }} > 0Split In Batches — Loop over each message
Process each unread message individually.
Batch size: 1AI node (OpenAI / Claude) — Generate reply
Pass the customer message to an AI model and get a reply.
# OpenAI node prompt
System: You are a helpful customer support agent for our business.
Reply in the same language as the customer. Keep replies under 3 sentences.
User: {{ $json.data[0].message }}HTTP Request — Send the reply
Post the AI-generated reply back to the customer.
Method: POST
URL: https://nashir.ai/api/v1/messages/{{ $('Split In Batches').item.json.data[0].id }}/reply
Headers: Authorization: Bearer up_your_api_key_here
Content-Type: application/json
Body: { "message": "{{ $json.choices[0].message.content }}" }Same pattern works for comments
/api/v1/messages with /api/v1/comments and the reply endpoint with /api/v1/comments/:id/reply to auto-reply to post comments instead.The same workflow for WhatsApp — only step 6 changes
WhatsApp replies are keyed by phone number, not by message id, so the send step uses POST /api/v1/messages instead of /messages/:id/reply. Fetch with ?platform=whatsapp_dm in step 2, then:
# Step 6 (WhatsApp) — HTTP Request node
Method: POST
URL: https://nashir.ai/api/v1/messages
Headers: Authorization: Bearer up_your_api_key_here
Content-Type: application/json
Body: {
"account_id": 900000101,
"to": "{{ $('Split In Batches').item.json.data[0].sender_id }}",
"message_type": "text",
"content": "{{ $json.choices[0].message.content }}"
}
# account_id is the numeric id from GET /api/v1/accounts (one per connected
# WhatsApp number) — it is fixed for your workflow, so hard-code it.Storing a reply is not sending it
POST /api/v1/messages/ingest only records a message in your nashir inbox — it never contacts WhatsApp. It exists to mirror in messages that another system already sent or received. If your workflow ends on /ingest, the reply will appear in your inbox and your customer will never receive it.n8n Community Node
Install the official nashir node package in your own n8n — no HTTP Request nodes needed.
Installation
Open your n8n instance → Settings → Community Nodes
Click Install
Type: n8n-nodes-nashir
Check “I understand the risks” → Click Install
Search “Nashir” in the node panel — done.
n8n-nodes-nashirKeep it updated from Settings → Community Nodes. WhatsApp templates, documents and videos need version 0.18.0 or later; Show Typing needs 0.19.0 or later. The npm page shows the latest version.
Available actions
Nashir WhatsApp
- ·Send Message
- ·Show Typing
- ·Reply to Message
- ·Mark as Read
- ·Get Messages
- ·Get Conversation History
- ·Get Contact
- ·Get AI Status
- ·Set AI Status
- ·Save Message to Inbox
Send Message: text, image, document, video and approved templates (with a template picker).
Nashir Facebook
- ·Publish Post
- ·Schedule Post
- ·Get Posts
- ·Delete Post
- ·Get Messages
- ·Reply to Message
- ·Get Comments
- ·Reply to Comment
- ·Delete Comment
Nashir Instagram
- ·Publish Post
- ·Schedule Post
- ·Get Posts
- ·Delete Post
- ·Get Messages
- ·Reply to Message
- ·Get Comments
- ·Reply to Comment
- ·Delete Comment
Nashir TikTok
- ·Publish Media
- ·Publish Photos / Carousel
- ·Schedule Media
- ·Get Posts
- ·Delete Post
Nashir Contact
- ·Get Contact (CRM)
- ·Set Contact Field
- ·Tag Contact
- ·Set Lifecycle
- ·Get Conversation History
- ·Search Knowledge Base
Nashir LinkedIn · Telegram · Threads · YouTube
- ·LinkedIn: Publish, Schedule, Get, Delete Post
- ·Telegram: the same + Send Notification
- ·Threads: Publish, Schedule Post
- ·YouTube: Upload, Schedule, Get, Delete Video
The node uses your API key. Generate one in Settings → API Keys, add it once as a Nashir API credential, and every node reuses it. Account fields are dropdowns filled from your connected accounts.
Error responses
All errors return a JSON object with an error field and an appropriate HTTP status code. Sending endpoints also return code (branch on it), message and message_ar. nashir never answers 502 or 504: those come from our network edge, not from the API, so treat them like 503.
| Status | Meaning |
|---|---|
| 400 | Bad request — missing or invalid parameters |
| 401 | Unauthorized — API key missing or invalid |
| 402 | The WhatsApp Business account has a payment problem in Meta (waba_payment_issue) |
| 403 | Not allowed — plan, key permission, or a contact you may not message |
| 404 | Not found — resource does not exist or belongs to another team |
| 409 | Conflict — e.g. outside_window, or a person holds the chat |
| 422 | The request is valid but the platform (WhatsApp, Meta, TikTok, Telegram) refused it |
| 429 | Too many requests — wait and retry |
| 500 | Server error — try again or contact support |
| 503 | A platform or service is temporarily unreachable — retry (with the same idempotency_key) |