REST API Reference

v1

Use 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.

Base URLhttps://nashir.ai/api/v1

Authentication

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_here

Keep your key secret

Never expose your API key in client-side code or public repositories. Treat it like a password.

List posts

GET/api/v1/posts

Returns a paginated list of scheduled posts for your team.

Query parameters

ParameterTypeDescription
statusstringFilter by status: scheduled, published, partial (live on some accounts, failed on others), failed, draft
account_idstringFilter by platform Page ID (e.g. Facebook page_id like 552126474642948, Instagram user ID, LinkedIn URN). Get IDs from GET /accounts.
platformstringFilter by platform: facebook, instagram, linkedin, tiktok
scheduled_fromstringReturn posts scheduled after this ISO 8601 datetime
scheduled_tostringReturn posts scheduled before this ISO 8601 datetime
limitnumberResults per page (default: 20, max: 100)
pagenumberPage number (default: 1)

account_id filter

Pass the platform Page ID directly — e.g. 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

POST/api/v1/posts

Schedule a new post. The post will be published automatically at scheduled_at.

Request body

FieldTypeRequiredDescription
contentstringYesPost text (max 2200 chars)
platformsstring[]YesArray of platforms: facebook, instagram, linkedin, linkedin_business, tiktok
scheduled_atstringYesISO 8601 datetime (e.g. 2026-03-25T10:00:00Z)
image_urlstringNoPublic URL of an image to attach

TikTok — tiktok_options required

When 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

FieldTypeRequiredDescription
privacy_levelstringYesPUBLIC_TO_EVERYONE | MUTUAL_FOLLOW_FRIENDS | SELF_ONLY
disable_commentbooleanNoDisable viewer comments. Default: false
disable_duetbooleanNoDisable Duet (video only). Default: false
disable_stitchbooleanNoDisable Stitch (video only). Default: false
brand_content_togglebooleanNoEnable content disclosure. Default: false
brand_organic_togglebooleanNoYour Brand (organic) — requires brand_content_toggle: true. Default: false
brand_branded_content_togglebooleanNoBranded 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.

PlatformSupported content
facebookText, image, video supported
instagramRequires image or video (no text-only posts)
linkedinText and image supported (personal account)
linkedin_businessText, image, and video supported (organization page)
tiktokVideo required (.mp4), no images supported

TikTok requires a video

TikTok posts require a video file. Posts scheduled to TikTok without a video will fail.

Get a post

GET/api/v1/posts/:id

Returns 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

DELETE/api/v1/posts/:id

Delete 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

GET/api/v1/accounts

Returns 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.

Featurelinkedin (Personal)linkedin_business (Business)
Posts asYour personal profileYour organization page
Use caseThought leadership, personal brandCompany announcements, brand content
Supported mediaText, imageText, image, video
Token independence✓ Independent✓ Independent

Tip

You can connect both LinkedIn Personal and Business at the same time. Reconnecting one never affects the other. If a token expires, reconnect only that account.

TikTok notes

Video required

TikTok requires a video file (.mp4). Posts scheduled to TikTok without a video will automatically fail. Images are not supported.

TikTok is currently in sandbox mode — posts are published as private. Public posting becomes available after TikTok app review approval.

Platform support matrix

PlatformText onlyImageVideoDMsComments
Facebook✓✓✓✓✓
Instagram✗✓✓ (Reels)✓✓
LinkedIn Personal✓✓✗✗✗
LinkedIn Business✓✓✓✗✗
TikTok✗✗✓✗✗

Register a webhook

POST/api/v1/webhooks

Register 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

GET/api/v1/messages

Returns direct messages received by your connected accounts.

Query parameters

ParameterTypeDescription
platformstringFilter by platform: facebook_dm or instagram_dm
is_readbooleanFilter by read status: true or false
account_idstringFilter by platform Page ID (e.g. 552126474642948). Only returns messages received by that specific page.
limitnumberResults per page (default: 20, max: 100)
offsetnumberNumber 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

GET/api/v1/comments

Returns comments left on your Facebook posts and Instagram media.

Query parameters

ParameterTypeDescription
platformstringFilter by platform: facebook or instagram
is_readbooleanFilter by read status: true or false
account_idstringFilter by platform Page ID (e.g. 552126474642948). Only returns comments on that specific page.
limitnumberResults per page (default: 20, max: 100)
offsetnumberNumber 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

POST/api/v1/messages/:id/reply

Send 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

FieldTypeRequiredDescription
messagestringYesThe reply text to send
pageIdstringNoFacebook/Instagram Page ID to reply from. If omitted, uses the page stored on the message or the first connected account.
skip_presentationbooleanNotrue 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

PATCH/api/v1/messages/:id/read

Mark 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

POST/api/v1/messages

Send 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

FieldTypeRequiredDescription
account_idnumberYesWhich WhatsApp number to send from — the numeric id from GET /api/v1/accounts (NOT the WhatsApp phone_number_id).
tostringYesThe customer's phone number in international format, e.g. +9647001234567.
message_typestringNotext (default), image, document, video, or template — see "Send a document or a video" and "Send a WhatsApp template to one number" below.
contentstringYes*The message text. Required when message_type is text. For document and video it is an optional caption.
image_urlstringYes*Public JPEG/PNG URL. Required when message_type is image (WhatsApp rejects WebP for images).
document_urlstringYes*Public https URL of the file (for example a PDF). Required when message_type is document.
filenamestringNoThe file name the customer sees for a document, e.g. company-profile.pdf.
video_urlstringYes*Public https URL of an MP4 video. Required when message_type is video.
dry_runbooleanNotrue = 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_idnumberNoThe inbox id of the message you are answering, so the reply threads to it.
skip_presentationbooleanNotrue 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_keystringNoUp 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

CaseYou getWhat it means
Sent201 + message_idWhatsApp 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 suppressed200, no message_idThe 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 window409 outside_windowWhatsApp 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 plan403 plan_requiredWhatsApp is a paid feature, or (whatsapp_number_blocked) the number is currently blocked from sending.
Wrong account_id404 account_not_foundThat id is not an active WhatsApp account on your team — list them with GET /api/v1/accounts.
WhatsApp refused it422 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.

CaseYou getWhat it means
Documents and videos are not enabled for your team403 inbox_media_not_enabledNothing 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 https400 invalid_requestdocument_url or video_url must be a public https URL.
Outside the 24h window409 outside_windowNothing is sent. Use an approved template (a template can carry a document or video header).
"dry_run": true200 + "dry_run": trueA 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.

POST/api/v1/messages/typing
FieldRequiredMeaning
account_idYesThe WhatsApp number the customer wrote to: social_account_id in the message.received webhook, or the id from GET /api/v1/accounts.
message_idYes, or nashir_message_idThe WhatsApp message id from the message.received webhook (message_id).
nashir_message_idInstead of message_idThe 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

  1. It marks the message read. WhatsApp shows typing only together with the blue ticks, on that message and every earlier one in the chat.
  2. It lasts up to 25 seconds, or until you reply, whichever comes first.
  3. Use it only if you will reply. A customer who sees typing and then gets nothing is left waiting.
  4. 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.

codeHTTPMeaning
invalid_request400account_id or message_id is missing or not valid.
account_not_found404That WhatsApp number is not connected to your team, or its connection has expired.
message_not_found404No message with that id on this number in your team.
not_inbound422The message was sent by your team, not by the customer.
chat_controlled409A person on your team holds the chat. control says who and until when.
whatsapp_not_on_plan403WhatsApp is not included in your current plan.
subscription_expired403Your subscription has expired.
forbidden403This API key may not reply on this number.
meta_rejected422WhatsApp refused. meta_code and meta_message carry WhatsApp’s own reason (for example a message id older than 30 days).
account_reconnect_required422The number’s connection has expired. Reconnect it in Channels.
meta_rate_limited429WhatsApp is limiting this number. Wait and try again.
whatsapp_unreachable503We 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

POST/api/v1/comments/:id/reply

Post 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

FieldTypeRequiredDescription
messagestringYesThe reply text to post
pageIdstringNoFacebook/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.

FieldMeaning
control.ownerbot: your bot may answer. human: do not answer.
control.sinceWhen the hold started. null when there is no hold.
control.untilWhen the hold ends by itself. null means no set end.
control.reasonWhy the chat is held, for example manual_pause, agent_replied, staff_takeover or handoff.
social_account_idThe WhatsApp number that received the message. Send it as account_id in your API calls.
recent_turnsUp 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

  1. Right after the Webhook node, add an IF node that continues only when {{ $json.body.data.control.owner }} equals bot. This saves the AI call when a person holds the chat.
  2. 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.
  3. End that branch when the response has code chat_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.

FieldMeaning
platformwhatsapp, facebook_dm, facebook_comment, instagram_dm, instagram_comment, website_chat, tiktok_dm or tiktok_comment.
keyThe chat. On WhatsApp, use phone from the forward payload.
account_idWhich WhatsApp number. Use social_account_id from the forward payload.
actionPOST only: take or release.
timeout_secondsOptional, 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.
reasonOptional, 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 }
StatusMeaning
200Done. The body is the chat’s current state.
400A field is wrong. The error says which.
403This key may not reply on that business.
404POST 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"
  }
}
FieldMeaning
changetake, renew, release or expire.
ownerWho holds the chat after this change: human or bot.
actorWho 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.

FieldMeaning
channelfacebook or instagram.
sender_idThe customer. Use it as key in the control API.
sender_nameThe customer’s name, when Meta gives it.
page_idThe Page or Instagram account that received the message.
nashir_message_idThe id to reply to. Use it as :id in the reply route.
message_idMeta’s id for the message.
content, media_type, media_urlThe message.
control, social_account_id, recent_turnsThe 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 getMeaning
200Sent.
409 chat_controlled_by_humanA person holds the chat. Do not retry.
424 outside_messaging_windowMeta 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_threadAnother app controls this conversation on Meta, such as Meta Business AI. Check Conversation Routing in the Page’s settings.
424Any 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.

EndpointSendReturns
GET /api/v1/conversations/ai-statusQuery: 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-statusWhatsApp, older form.The same five fields.
POST /api/v1/conversations/pauseplatform, 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/pauseWhatsApp, older form: phone, duration_seconds (60 to 86400), optional reason (default handoff).ok, phone, paused_until, duration_seconds.
POST /api/v1/conversations/:phone/ai-toggleWhatsApp: 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

GET/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

POST/api/v1/messages
FieldRequiredMeaning
account_idYesThe WhatsApp number that sends it (the id from GET /api/v1/accounts).
toYesThe customer’s number in international format, e.g. +9647001234567.
message_typeYes"template".
templateYes{ "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.
variablesIf the body has {{1}}…Body values, in order: ["Ali", "2026-12-15"] or {"1": "Ali", "2": "2026-12-15"}.
header_variablesIf the header has {{1}}Same shape, for a text header.
button_variablesIf a link button takes a valueThe end of the link per button index: {"0": "INV-20931"}. For a carousel card: {"card_0_1": "…"}.
header_media_urlNoA public https link to use as the image, video or document header for this send instead of the template’s own.
idempotency_keyNoSee Idempotency below. Strongly recommended.
dry_runNoLeave 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.

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.

StatuscodeMeaning
400invalid_requestA field is missing or malformed. message says which.
404account_not_foundaccount_id is not an active WhatsApp number of your team.
404template_not_foundNo such template on this number. available_languages lists the languages that exist for that name.
422template_not_approvedThe template is pending, rejected or paused.
422template_not_supportedAuthentication template, or named variables.
422variable_count_mismatchWrong number of values. expected and got show where.
403recipient_opted_outThe contact opted out (in nashir or in WhatsApp).
403recipient_blockedNever-message list, do not contact, or archived. reason says which.
422recipient_not_on_whatsappWhatsApp could not deliver to this number (Meta 131026).
402waba_payment_issueYour WhatsApp Business account has no valid payment method in Meta.
422account_reconnect_requiredThe WhatsApp number’s connection expired (Meta 190). Reconnect it in Channels.
409outside_windowOnly for text, image, document, video and options: the 24-hour window is closed. Send a template.
422meta_rejectedAny other refusal by WhatsApp. meta_code and meta_message carry Meta’s answer.
429meta_rate_limitedWhatsApp is slowing this number down. Retry later with the same idempotency_key.
403trial_limit_reachedThe trial’s template allowance is used up.
403plan_required · subscription_expired · forbidden · whatsapp_number_blockedPlan, key permission or number health.
503whatsapp_unreachable · consent_check_unavailableTemporary. 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.

CaseYou get
Same key, same request, within 24 hoursThe original response, replayed. Nothing is sent.
Same key, different request422 idempotency_key_reused.
Same key while the first is still running409 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):

GET/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

POST/api/v1/broadcasts

Send 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

FieldTypeRequiredDescription
namestringYesCampaign name
templateIdnumberYesId of one of your WhatsApp templates
contactFilterobjectNoWho receives it, e.g. {"type":"all"} (default) or {"type":"tag","tag":"vip"}
variableValuesobjectNoValues for the template variables: {"1":"Ali","2":"20"}
scheduledAtstringNoWhen to send — see "Scheduling time" below. Omit to send now.
socialAccountIdnumberIf 2+ numbersWhich WhatsApp number sends it
dry_runbooleanNotrue = 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 sendIt means
2026-10-20T15:30No 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:00An explicit offset is honoured exactly: 15:30 at UTC+3 (12:30 UTC).
2026-10-20T12:30:00ZZ means UTC: 12:30 UTC.

Which local time?

The time zone of the business that owns the sending WhatsApp number; if it has none, your team's time zone; if neither is set, your team's country when that country has a single time zone. If none of these is known, a time without a zone is refused with timezone_unknown — it is never guessed. Set your time zone in Settings → Team, or send the time with an offset or Z.

Scheduling errors

StatuscodeWhen
400invalid_scheduled_atNot an ISO 8601 date and time (e.g. "tomorrow", "20/10/2026 15:30")
400scheduled_in_pastThe time has already passed (2 minutes of clock skew are allowed)
409timezone_unknownNo 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.

1

Trigger — Schedule node

Runs every 5 minutes (or use a Webhook trigger for real-time response).

# Schedule node
Interval: Every 5 minutes
2

HTTP 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_here
3

IF node — Check for new messages

Only continue if the response contains at least one message.

Condition: {{ $json.pagination.total }} > 0
4

Split In Batches — Loop over each message

Process each unread message individually.

Batch size: 1
5

AI 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 }}
6

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

Replace /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

1

Open your n8n instance → Settings → Community Nodes

2

Click Install

3

Type: n8n-nodes-nashir

4

Check “I understand the risks” → Click Install

5

Search “Nashir” in the node panel — done.

npm packagen8n-nodes-nashir

Keep 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.

StatusMeaning
400Bad request — missing or invalid parameters
401Unauthorized — API key missing or invalid
402The WhatsApp Business account has a payment problem in Meta (waba_payment_issue)
403Not allowed — plan, key permission, or a contact you may not message
404Not found — resource does not exist or belongs to another team
409Conflict — e.g. outside_window, or a person holds the chat
422The request is valid but the platform (WhatsApp, Meta, TikTok, Telegram) refused it
429Too many requests — wait and retry
500Server error — try again or contact support
503A platform or service is temporarily unreachable — retry (with the same idempotency_key)
Nashir