البناء باستخدام Conviro.
قم بتوصيل محادثات العملاء ومساعدة الذكاء الاصطناعي والتقاط العملاء المتوقعين والأتمتة بمكدسك الحالي باستخدام واجهات برمجة تطبيقات REST وخطافات الويب.
- عنوان URL الأساسي
- api.conviro.io/v1/api
- مصادقة
- رمز حامل
- الاستجابة
- في قائمة الانتظار ACK + webhook
$ curl -s https://api.conviro.io/v1/api/sessions/sess_3f2a/messages \
-H "Authorization: Bearer cvr_live_***" \
-d '{"content":"How do I return an order?"}'
# 201 Created — the AI reply follows via the message.new webhook
{
"messageId": "6d1f0c6e-3b7a-...",
"role": "system",
"content": "Message received. Preparing a response...",
"status": "queued"
}بداية سريعة
طلبك الأول الناجح
قم بإنشاء مفتاح محدد النطاق، وافتح جلسة، وأرسل رسالة، وتعامل مع الرد غير المتزامن دون الخلط بين الإقرار والإجابة.
جرب العرض التوضيحي المكتوب بدون مفتاح API
5 متطلبات/دقيقة لكل IPcurl -X POST https://useconviro.com/api/developers/demo \
-H "Content-Type: application/json" \
-d '{"content": "I want to return my last order"}'- 1
قم بإنشاء مفتاح API
اذهب الى الإعدادات → مفاتيح واجهة برمجة التطبيقات وإنشاء مفتاح باستخدام
chat:writeالنطاق. يتم عرضه مرة واحدة - قم بتخزينه في مديرك السري.تتوفر مفاتيح API في الخطط Pro والخطط الأعلى.
احصل على مفتاح API - 2
أرسل رسالة
تنشئ الأمثلة جلسة باستخدام POST /sessions، ثم ترسل رسالة الزائر إلى POST /sessions/:id/messages باستخدام رمز Bearer المميز.
- 3
التعامل مع الرد
يمكنك العودة
messageIdوالحالة "في قائمة الانتظار". يتم إنتاج رد الذكاء الاصطناعي بشكل غير متزامن - اشترك في message.new webhook، أو اقرأ الجلسة باستخدام GET /sessions/:id.
const BASE = 'https://api.conviro.io/v1/api';
const key = process.env.CONVIRO_API_KEY;
if (!key) throw new Error('CONVIRO_API_KEY is not set');
const headers = {
Authorization: `Bearer ${key}`,
'Content-Type': 'application/json',
};
// 1. Open a session for one assistant.
const sessionRes = await fetch(`${BASE}/sessions`, {
method: 'POST',
headers,
body: JSON.stringify({ chatbotId: process.env.CONVIRO_CHATBOT_ID }),
});
if (!sessionRes.ok) throw await conviroError(sessionRes);
const session = await sessionRes.json();
// 2. Send the visitor's message.
const sendRes = await fetch(`${BASE}/sessions/${session.id}/messages`, {
method: 'POST',
headers,
body: JSON.stringify({ content: 'Can I return an item I bought yesterday?' }),
});
if (!sendRes.ok) throw await conviroError(sendRes);
const ack = await sendRes.json();
console.log(ack.status); // "queued"
// The ASSISTANT REPLY IS NOT IN THAT RESPONSE. It is produced
// asynchronously. Receive it on the message.new webhook, or poll
// GET /v1/api/sessions/:id. Awaiting this call for the answer waits
// forever — the response is an acknowledgement, nothing more.
/** Parses whichever of the three error bodies came back. */
async function conviroError(res: Response): Promise<Error> {
const body = await res.json().catch(() => ({}) as Record<string, unknown>);
// Validation failures put an ARRAY in `message`; everything else a string.
const raw = (body as { message?: string | string[] }).message;
const message = Array.isArray(raw) ? raw.join('; ') : raw ?? res.statusText;
const err = new Error(`Conviro ${res.status}: ${message}`);
// Only the per-key 429 carries retryAfter, and it has no timestamp field.
(err as Error & { retryAfter?: number }).retryAfter =
(body as { retryAfter?: number }).retryAfter ??
Number(res.headers.get('retry-after')) ||
undefined;
return err;
}الاستجابة
{
"messageId": "6d1f0c6e-3b7a-4f0e-9a52-8c1e2d4b7a90",
"role": "system",
"content": "Message received. Preparing a response...",
"createdAt": "2026-04-14T10:22:03.412Z",
"status": "queued"
}عرض واجهة برمجة التطبيقات التفاعلية
استجابات مكتوبة وطلبات HTTP حقيقية
تقوم نقطة النهاية ذات المعدل المحدود هذه بإرجاع أمثلة حتمية ومحاكاة زمن الاستجابة. لا يستدعي نموذج الذكاء الاصطناعي. ردود عمليات API الإنتاج المصادق عليها بشكل غير متزامن.
وكيل تجريبي
POST /api/developers/demo
العرض التجريبي - الردود المكتوبة والكمون الاصطناعي؛ لا يتم استدعاء نموذج الذكاء الاصطناعي. تجيب واجهة برمجة التطبيقات الحقيقية بشكل غير متزامن.
مرحبًا - أعرض أمثلة مكتوبة حتى تتمكن من فحص نقطة النهاية التجريبية بأمان.
ما عاد API
{
"intent": "greeting",
"confidence": 1,
"model": "scripted-demo",
"message": {
"role": "assistant",
"content": "مرحبًا - أعرض أمثلة مكتوبة حتى تتمكن من فحص نقطة النهاية التجريبية بأمان."
}
}نقطة النهاية التجريبية محدودة بالسعر 5 req/min per IP. حدود الإنتاج خاصة بالمفتاح وتتبع أيضًا خطة مساحة العمل. تعامل مع 429 استجابة باستخدام "إعادة المحاولة بعد".
حالات الاستخدام
قم بتوصيل سير العمل حول كل محادثة
استخدم العمليات والأحداث ذات النطاق الضيق. تقوم البطاقات بتحميل الأمثلة المكتوبة ذات الصلة؛ لا تزال نتائج الإنتاج تعتمد على بياناتك وتكوينك.
كيف يعمل
الإقرار ليس رد الذكاء الاصطناعي
تؤكد مكالمة إرسال الرسالة أنه تم وضع العمل في قائمة الانتظار. صمم التكامل الخاص بك لاستهلاك الرد النهائي من خلال message.new أو قراءة جلسة لاحقة.
أرسل رسالة
POST /sessions/:id/messages
تلقي الاعتراف
201 · status: queued
تتم معالجة الرد
تدفق الإنتاج غير المتزامن
تستهلك الرد
message.new · GET /sessions/:id
- الاستجابة الأولية
- إقرار في قائمة الانتظار
- تسليم الرد
- قراءة Webhook أو الجلسة
- حدود المعدل
- مفتاح محدد ومستوى الخطة
مرجع
سطح واجهة برمجة التطبيقات
العمليات العامة أدناه مستمدة من نفس العقد المشترك المستخدم للتحقق من صحة واجهة برمجة التطبيقات. عنوان URL الأساسي الأساسي: https://api.conviro.io/v1/api
| الطريقة | المسار | النطاق المطلوب | الوصف |
|---|---|---|---|
| POST | /sessions | chat:write | Create a new chat session |
| GET | /sessions | chat:read | List sessions for incremental reconciliation (keyset cursor, metadata only — no transcripts) |
| GET | /sessions/:id/messages | chat:read | Paginated message history for a session (oldest first, keyset cursor) |
| GET | /sessions/:id | chat:read | Get session with last 50 messages |
| POST | /sessions/:id/messages | chat:write | Send a message and get AI response |
| POST | /sessions/:id/identify | chat:write | Identify the visitor in a session from your backend — no frontend change needed |
| POST | /knowledge | kb:write | Add a knowledge base item |
| DELETE | /knowledge/:id | kb:write | Delete a knowledge base item |
| GET | /analytics/summary | analytics:read | Get analytics summary |
| GET | /contacts | contacts:read | List contacts with pagination and filters |
| GET | /contacts/:id | contacts:read | Get single contact with stats |
| POST | /contacts | contacts:write | Create or find contact by email |
| PATCH | /contacts/:id | contacts:write | Update contact fields |
| GET | /lead-forms | chat:read or magento:module | List active lead forms |
| GET | /appointments/slots | appointments:read | Open booking slots for a chatbot (optionally one local date / service) |
| POST | /appointments | appointments:write | Book an appointment directly (trusted backend — no OTP) |
| GET | /appointments | appointments:read | List appointments (newest first) |
| DELETE | /appointments/:id | appointments:write | Cancel an appointment (also removes the calendar event) |
| GET | /webhooks | webhooks:write | List webhook subscriptions |
| POST | /webhooks | webhooks:write | Subscribe to an event (creates a webhook subscription) |
| DELETE | /webhooks/:id | webhooks:write | Unsubscribe (deletes a webhook subscription) |
| POST | /consent/whatsapp | consent:write | Record a WhatsApp marketing opt-in collected on your checkout or form, with the text shown |
chat:readRead sessions and their messages, and list lead forms.chat:writeCreate sessions, send messages, identify visitors.kb:readRead knowledge base items. Minted, but required by no public operation today.kb:writeCreate and delete knowledge base items, and drive the e-commerce sync endpoints.analytics:readRead the workspace analytics summary.webhooks:writeManage webhook subscriptions. Note this is required to LIST them as well as to change them — there is no webhooks:read scope, so a read-only integration still needs the write scope here.contacts:readRead CRM contacts. Returns PII.contacts:writeCreate and update CRM contacts — the records human agents work from.leads:writeCreate a lead: drop a new inbound record at the top of the funnel. Deliberately narrower than contacts:write, so an automation posting form fills does not also get the power to rewrite existing people. Minted, but required by no public operation today.appointments:readRead open slots and booked appointments.appointments:writeBook and cancel appointments.consent:writeRecord a WhatsApp marketing opt-in. Its own scope rather than riding on leads or contacts: a key that can post form fills should not also be able to assert that a person agreed to campaigns.magento:moduleWhat the Conviro Magento module (1.4.0+) needs and nothing more: it registers its store, delivers the store event outbox, reads the admin stats cards and lists lead forms. It reads no conversation and writes no knowledge-base item through the public API. The module's browser-mediated connect mints a key with only this scope, limited to the chosen assistant.خطافات الويب
استخدم بيانات اعتماد ضيقة. التحقق من كل حدث.
تستخدم مفاتيح API مصادقة Bearer ونطاقات صريحة. يتم توقيع عمليات تسليم Webhook باستخدام HMAC-SHA256 حتى يتمكن جهاز الاستقبال الخاص بك من التحقق من صحة نص الطلب الأولي قبل معالجته.
مفاتيح API ذات النطاق
قم بإنشاء مفاتيح على الإصدار Pro أو أعلى، وامنح النطاقات المطلوبة فقط، وقم بتقييد المفتاح بشكل اختياري للمساعدين المحددين. يظهر المفتاح الخام مرة واحدة.
احصل على مفتاح APIالتحقق من الجسم الخام
التحقق من صحة التوقيع ذي الطابع الزمني من خلال مقارنة زمنية ثابتة، ورفض الطلبات التي لا معنى لها، ثم الإقرار على الفور ومعالجة العمل بعد الاستجابة.
الأحداث
message.newA message was added to a session, by the visitor or by the assistant.session.startedA new conversation session was created.session.closedA session was closed.session.reopenedA closed conversation was reopened by staff with the explicit Reopen action (POST /sessions/:id/reopen).session.escalatedA session was escalated to a human.handoff.requestedA visitor asked for a human agent.lead.capturedA lead was captured from a conversation.lead.createdA lead record was created outside a chat — from an ad integration, a lead form, or an e-commerce order.lead_form.submittedA lead form was submitted.csat.submittedA CSAT rating was submitted.csat.receivedThe same rating as csat.ai.failedThe assistant could not produce an answer.ticket.createdA support ticket was opened.ticket.resolvedA support ticket was resolved.contact.createdA CRM contact was created.contact.updatedA CRM contact was updated.contact.mergedTwo CRM contacts were merged.contact.deletedA CRM contact was deleted.appointment.bookedAn appointment was booked. Not listed in the dashboard event picker — subscribe with "*" or by name.appointment.cancelledAn appointment was cancelled. Not listed in the dashboard event picker — subscribe with "*" or by name.lead.hotA lead crossed the hot-lead threshold. Not listed in the dashboard event picker — subscribe with "*" or by name.lead.updatedA lead record was corrected after capture. Not listed in the dashboard event picker — subscribe with "*" or by name.
الحمولة
{
"event": "session.closed",
"timestamp": "2026-04-14T10:22:03.412Z",
"data": {
"sessionId": "sess_3f2a...",
"chatbotId": "bot_123"
}
}التحقق من التوقيع
// Node.js (Express) — verify a Conviro webhook
import crypto from 'crypto';
// The RAW body is required. express.json() parses and discards it, and
// JSON.stringify(req.body) does NOT reproduce the signed bytes — key
// order and whitespace both change the digest.
app.post('/conviro/webhook',
express.raw({ type: 'application/json', limit: '1mb' }),
(req, res) => {
if (!verify(req.body, req.header('X-Webhook-Signature'))) {
return res.status(401).end();
}
res.status(200).end(); // acknowledge within 10s
void handle(JSON.parse(req.body.toString('utf8')));
});
const TOLERANCE_SECONDS = 300;
function verify(rawBody, header) {
if (!header) return false;
// Header format: t=<unix_seconds>,v1=<hex_digest>
const parts = new Map(header.split(',').map((p) => {
const i = p.indexOf('=');
return [p.slice(0, i).trim(), p.slice(i + 1).trim()];
}));
const timestamp = parts.get('t');
const signature = parts.get('v1');
if (!timestamp || !signature) return false;
// Replay window: without it, a captured payload is valid forever.
const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
if (!Number.isFinite(age) || age > TOLERANCE_SECONDS) return false;
// The digest covers "<timestamp>.<rawBody>" — NOT the body on its own.
const expected = crypto
.createHmac('sha256', process.env.CONVIRO_WEBHOOK_SECRET)
.update(timestamp + '.')
.update(rawBody)
.digest('hex');
const a = Buffer.from(signature, 'utf8');
const b = Buffer.from(expected, 'utf8');
// timingSafeEqual throws on a length mismatch, so check length first.
return a.length === b.length && crypto.timingSafeEqual(a, b);
}أدوات تطوير البرامج (SDKs).
استخدم عميل HTTP الذي تثق به بالفعل
لا تقوم Conviro بنشر SDK رسمي اليوم. تستخدم هذه الأمثلة الأساسية مكتبات HTTP القياسية ويتم الاحتفاظ بها من خلال عقد API المشترك.
const BASE = 'https://api.conviro.io/v1/api';
const key = process.env.CONVIRO_API_KEY;
if (!key) throw new Error('CONVIRO_API_KEY is not set');
const headers = {
Authorization: `Bearer ${key}`,
'Content-Type': 'application/json',
};
// 1. Open a session for one assistant.
const sessionRes = await fetch(`${BASE}/sessions`, {
method: 'POST',
headers,
body: JSON.stringify({ chatbotId: process.env.CONVIRO_CHATBOT_ID }),
});
if (!sessionRes.ok) throw await conviroError(sessionRes);
const session = await sessionRes.json();
// 2. Send the visitor's message.
const sendRes = await fetch(`${BASE}/sessions/${session.id}/messages`, {
method: 'POST',
headers,
body: JSON.stringify({ content: 'Can I return an item I bought yesterday?' }),
});
if (!sendRes.ok) throw await conviroError(sendRes);
const ack = await sendRes.json();
console.log(ack.status); // "queued"
// The ASSISTANT REPLY IS NOT IN THAT RESPONSE. It is produced
// asynchronously. Receive it on the message.new webhook, or poll
// GET /v1/api/sessions/:id. Awaiting this call for the answer waits
// forever — the response is an acknowledgement, nothing more.
/** Parses whichever of the three error bodies came back. */
async function conviroError(res: Response): Promise<Error> {
const body = await res.json().catch(() => ({}) as Record<string, unknown>);
// Validation failures put an ARRAY in `message`; everything else a string.
const raw = (body as { message?: string | string[] }).message;
const message = Array.isArray(raw) ? raw.join('; ') : raw ?? res.statusText;
const err = new Error(`Conviro ${res.status}: ${message}`);
// Only the per-key 429 carries retryAfter, and it has no timestamp field.
(err as Error & { retryAfter?: number }).retryAfter =
(body as { retryAfter?: number }).retryAfter ??
Number(res.headers.get('retry-after')) ||
undefined;
return err;
}أخطاء
تحليل الحالة، ثم الهيئة التي تلقيتها
تتضمن معظم الأخطاء رمز الحالة والرسالة والطابع الزمني. تتضمن الاستجابات لكل مفتاح 429 بدلاً من ذلك إعادة المحاولة بعد. تعامل مع الرسالة بشكل دفاعي ولا تفترض أن كل جسم غير 2xx له شكل واحد متطابق.
| الحالة | الاسم | عندما يحدث ذلك |
|---|---|---|
| 400 | Bad Request | The request was rejected by the handler. `message` is a single string. A 4xx may additionally carry `error`, `code`, `reason` or `state`: a machine-readable name, always one identifier (lower_snake or UPPER_SNAKE). Branch on that name when it is present, never on `message`; most errors carry none. |
| 400 | Bad Request (validation) | Body validation failed. Same status and same keys as bad_request, but `message` is an ARRAY of strings, one per failed constraint. Parse it as `string | string[]` or the most common 400 in the API will crash your error handler. Unknown fields also land here: the global pipe runs with forbidNonWhitelisted, so an undeclared field is a 400 rather than being ignored — except on the two contacts endpoints that bind no DTO class, where unknown fields pass through silently. |
| 401 | Unauthorized | Missing or malformed Authorization header, or an invalid, revoked or expired key. Never retry: the credential will not become valid. |
| 403 | Forbidden | The key is valid but lacks the scope, or is restricted to assistants that do not include the one referenced. Scopes are evaluated with OR: holding ANY of the listed scopes is enough. Fix the key, do not retry. |
| 404 | Not Found | No such resource in your workspace. A resource that exists in another tenant is a 404 here, not a 403 — the tenant filter is applied before the lookup, so cross-tenant ids are indistinguishable from absent ones. That is deliberate. |
| 429 | Too Many Requests | Per-key rate limit exceeded. THIS BODY IS DIFFERENT: it carries `retryAfter` and NO `timestamp`, because the guard writes it directly to the response and never reaches the global filter. A `Retry-After: 60` header is set. The separate plan-level limiter produces a 429 with a different message and no `retryAfter`. Retry after the header says, with backoff. |
| 500 | Server Error | Something failed on our side. The message is always this fixed string — internal detail is logged, never returned. Retry with exponential backoff. |
{
"statusCode": 401,
"message": "Invalid or expired API key",
"timestamp": "2026-09-20T10:22:03.412Z"
}تكريم إعادة المحاولة بعد يوم 429 واستخدام التراجع الأسي للفشل القابل لإعادة المحاولة. لا تقبل نقاط نهاية الكتابة العامة مفتاح العجز، لذا تأكد من الكتابة بشكل آمن قبل تكرارها.
جاهز عندما تكون
قم بتوصيل Conviro بالمكدس الخاص بك
أنشئ مساحة عمل، واختر Pro أو أعلى، وأصدر مفتاح API محدد النطاق عندما تكون مستعدًا للانتقال من العرض التوضيحي المكتوب إلى الإنتاج.
احصل على مفتاح API