API reference — Zokiar

Base URL

https://portal.zokiar.com

Authentication

Public endpoints do not use API keys. Each one is tied to a business by its Client ID in the URL. Incoming webhooks are checked with a signature from the sender:

Shopify sends X-Shopify-Hmac-Sha256, checked with your Shopify webhook secret.
Meta (Facebook Lead Ads and WhatsApp) sends X-Hub-Signature-256, checked with the Meta app secret.

Dashboard endpoints, such as managing contacts, campaigns and messages, require a signed-in user. They are not available for third-party use yet. Developer API keys are on the roadmap. Contact us if you need access to your data programmatically.

Errors

Status	Meaning
`403`	Webhook signature did not match, or the verification token is wrong.
`404`	The Client ID is unknown, or the chat widget is not enabled for that business.
`422`	Request body failed validation (for example, a message longer than 4000 characters).
`200`	Accepted. For chat, the body contains the reply.

Health

GET/health

Returns {"status": "ok"}. Use it for uptime checks. It does not touch the database.

Website chat

GET/api/webchat/{client_id}/config

Returns whether the chat widget is enabled for the business, and the welcome message to show.

{
  "enabled": true,
  "welcome_message": "Hi! How can we help you today?"
}

POST/api/webchat/{client_id}/message

Sends one visitor message and returns the AI reply. The session_id identifies the visitor's browser session, so generate it once per visitor and reuse it.

Field	Type	Rules
`session_id`	string	8 to 128 characters
`message`	string	1 to 4000 characters

curl -X POST https://portal.zokiar.com/api/webchat/YOUR_CLIENT_ID/message \
  -H "Content-Type: application/json" \
  -d '{"session_id": "visitor-abc12345", "message": "Do you deliver to Pune?"}'

Response:

{
  "reply": "Yes, we deliver to Pune in 2 to 3 days.",
  "handoff": false
}

handoff is true when the visitor has been passed to a team member. Later messages in that session are not answered by the AI.
Each session allows a limited number of messages. After that the reply asks the visitor to start a new chat.
If the business's account balance is empty, the reply asks the visitor to try again later.

Shopify webhooks

POST/shopify/webhook/{client_id}/order-placed

Receives Shopify's orders/create event. Sends the order confirmation template to the customer's phone number, if the order has one. Returns 200 when accepted.

POST/shopify/webhook/{client_id}/order-fulfilled

Receives Shopify's fulfillments/create event. Sends the shipping update template to the customer. Returns 200 when accepted.

Facebook Lead Ads webhook

GET/webhook/facebook-leads

Verification handshake used by Meta. Meta sends hub.mode, hub.verify_token and hub.challenge. If the token matches, the challenge is returned as plain text.

POST/webhook/facebook-leads

Receives leadgen events from Meta. Zokiar fetches the form answers and creates a contact, then routes it to a team member. Requests must carry a valid X-Hub-Signature-256.

WhatsApp webhook

Meta calls /webhook/whatsapp to deliver incoming WhatsApp messages and delivery statuses. This is configured in your Meta app by Zokiar and is not called by clients.

What is not public yet

Create, read and update endpoints for contacts, messages and campaigns (dashboard only)
Developer API keys with scopes and rate limits
Outgoing webhooks that notify your own systems about new messages

These are on the roadmap. If you need one now, contact us.

Zokiar API