للمطورين

مرجع الواجهة البرمجية لـ aiyourbusiness

أرسل رسائل وقوالب واتساب من أنظمتك واتبع حالة تسليمها. المرجع التقني أدناه باللغة الإنجليزية.

تنزيل OpenAPI بصيغة JSON إدارة مفاتيح APIالإصدار 1.0.0

العنوان الأساسي: /api/v1

المصادقة

Create a key in Settings → API keys (workspace owner, Professional plan). The full key (ga_live_…) is shown once; only its hash is stored. Send it on every request over HTTPS:

curl https://app.aiyourbusiness.online/api/v1/whatsapp/messages \
  -H "Authorization: Bearer $AIYB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{
    "from_phone_number_id": "123456789012345",
    "to": "+201001234567",
    "text": "Your order #1042 has shipped."
  }'

Keep keys on your server. Revoking a key in the dashboard stops it immediately.

الصلاحيات

whatsapp:sendSend WhatsApp text messages and templates.
whatsapp:readList approved templates and read message status.
messenger:sendReserved for Messenger (not available yet).
instagram:sendReserved for Instagram (not available yet).
*Every scope, including future ones.

A key can also be limited to some agents: requests for a number connected to another agent get 403 agent_not_authorized.

نقاط النهاية

GET/api/v1/healthCheck an API key

Validates the key and the plan; any scope works.

POST/api/v1/whatsapp/messagesSend a text messagewhatsapp:send

Sends free-form text inside the 24-hour customer service window (the recipient wrote to this number in the last 24 hours). Outside it the answer is 409 window_closed; send a template instead. Requires whatsapp:send.

POST/api/v1/whatsapp/templates/sendSend a template messagewhatsapp:send

Sends an approved template at any time. The template is checked against the approved templates of the number's WhatsApp Business Account (422 template_not_approved) and the parameter counts against its body, header and URL buttons (422 template_param_mismatch). Requires whatsapp:send.

GET/api/v1/whatsapp/templatesList approved templateswhatsapp:read

Approved templates of a number. Give connection_id or from_phone_number_id. Requires whatsapp:read.

GET/api/v1/messages/{id}Get a messagewhatsapp:read

Delivery status, timestamps and error of a message. Requires whatsapp:read.

GET/api/v1/openapi.jsonThis documentبدون

POST/api/v1/messenger/messagesMessenger endpoints (not available yet)بدون

POST/api/v1/instagram/messagesInstagram endpoints (not available yet)بدون

الأخطاء

Every error has the same envelope. Branch on error.code; quote correlation_id (also the X-Correlation-Id header) when contacting support.

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the whatsapp:send scope.",
    "required_scope": "whatsapp:send"
  },
  "correlation_id": "0b7c8a0e-3f4d-4a43-a1d2-2e8e5a9c6b71"
}

رمز الحالة	رمز الخطأ	الوصف
400	invalid_request	A field is missing or invalid; param names it.
400	invalid_idempotency_key	The Idempotency-Key header is empty or longer than 255 characters.
401	invalid_api_key	No key, or a malformed, unknown, expired or revoked key.
403	insufficient_scope	The key lacks the scope in required_scope.
403	agent_not_authorized	The key is restricted to other agents.
403	plan_required	The workspace's plan does not include the API.
403	https_required	The request was not made over HTTPS.
404	connection_not_found	No connected WhatsApp number with that id in this workspace.
404	message_not_found	No such message in this workspace.
409	window_closed	The 24-hour window is closed (free_form_until tells when it closed); send a template.
409	connection_unavailable	The number exists but is not connected right now.
409	idempotency_in_progress	A request with the same Idempotency-Key is still running.
413	payload_too_large	The body is larger than 64 KB.
422	template_not_approved	No approved template with that name and language for the number.
422	template_param_mismatch	The parameters do not match the template's variables.
422	idempotency_key_mismatch	The Idempotency-Key was used with a different request.
429	rate_limited	Too many requests; wait Retry-After seconds.
500	internal_error	Our side failed; retry with the same Idempotency-Key.
501	not_implemented	Messenger and Instagram endpoints are not available yet.

منع التكرار

Send an Idempotency-Key header (1–255 characters, e.g. a UUID or your own order id) on POST requests. For 24 hours, a retry with the same key and the same body returns the first response with Idempotent-Replayed: true and sends nothing again.

Same key, different body: 422 idempotency_key_mismatch.
Same key while the first request is still running: 409 idempotency_in_progress.
A 5xx is not stored, so retrying with the same key is safe.

حدود الطلبات

60 requests per minute per key (a token bucket, so short bursts are fine). Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds when the bucket is full again). Over the limit you get 429 rate_limited with Retry-After in seconds.