ابنِ على إس تي إس كونكت.

نظرة عامة

لكل حساب واجهة REST نفسها. أنشئ جهات الاتصال وحدّثها، وافتح المحادثات، وأرسل الرسائل وقوالب واتساب، وأدر الوسوم، وكل ذلك من أنظمتك الخاصة.

العنوان الأساسي

https://app.stsconnect.chat

تقع كل النقاط الطرفية تحت

/api/v1/accounts/{account_id}

أرسل مفتاحك في الترويسة

api_access_token

أول استدعاء لك: إنشاء جهة اتصال

curl -X POST https://app.stsconnect.chat/api/v1/accounts/ACCOUNT_ID/contacts \
  -H "api_access_token: sts_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sara Haddad", "phone_number": "+971501234567"}'

المفاتيح والنطاقات

ينشئ المسؤول المفاتيح من صندوق الوارد، في «الإعدادات» ثم «الواجهة البرمجية والويبهوك» ثم «إنشاء مفتاح». ويبدأ كل مفتاح بـ sts_live_.

• نطاقان: «قراءة» لقراءة البيانات، و«قراءة وكتابة» لإرسال الرسائل وتعديل السجلات.

• تنتهي صلاحية المفتاح بعد 30 أو 90 أو 365 يومًا، أو لا تنتهي أبدًا.

• حتى 25 مفتاحًا نشطًا لكل حساب.

• يظهر المفتاح مرة واحدة فقط. نحفظ منه بصمة مشفرة، لذا لا يمكن إظهار مفتاح ضائع مرة أخرى: ألغِه بزر «إلغاء المفتاح» وأنشئ مفتاحًا جديدًا.

• يعمل المفتاح باسم الحساب، لا باسم شخص بعينه.

الأخطاء

• تفشل الكتابة بمفتاح قراءة باستجابة 403 ورمز الخطأ api_key_read_only.

• تفشل النقاط الطرفية التي لا يمكن للمفاتيح استخدامها، مثل إدارة خطافات الويب أو المفاتيح، باستجابة 403 ورمز الخطأ api_key_endpoint_not_allowed.

الحدود

• 120 طلبًا في الدقيقة لكل مفتاح، ولا يتجاوز حد الحساب أبدًا.

• 300 طلب في الدقيقة لكل حساب، و30 أثناء التجربة المجانية. نوافذ ثابتة مدتها 60 ثانية.

• تحمل كل استجابة الترويسات X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset.

• عند تجاوز الحد تكون الاستجابة HTTP 429 مع الترويسة Retry-After والرمز rate_limited في الجسم.

• البحث في جهات الاتصال: 100 طلب في الدقيقة لكل حساب.

خطافات الويب

أضف خطاف ويب من صندوق الوارد، في «الإعدادات» ثم «الواجهة البرمجية والويبهوك». تُرسل الأحداث إلى عنوانك فور حدوثها.

الجسم هو تمثيل JSON للمورد مع المفتاح event في المستوى الأعلى. وتتضمن أربعة أحداث الحقل changed_attributes أيضًا: conversation_updated وcontact_updated وinbox_updated وconversation_status_changed.

يرسل زر «إرسال اختبار» حدثًا تجريبيًا: { "event": "webhook_test", ... }

الأحداث التي يمكنك الاشتراك بها

• message_created
• message_updated
• conversation_created
• conversation_updated
• conversation_status_changed
• contact_created
• contact_updated
• inbox_created
• inbox_updated
• webwidget_triggered
• conversation_typing_on
• conversation_typing_off

التحقق من التوقيع

يحمل كل إرسال أربع ترويسات:

X-STS-Connect-Timestamp

ثواني يونكس.

X-STS-Connect-Signature

sha256= ثم بصمة HMAC-SHA256 بنظام hex للسلسلة {timestamp}.{raw body} باستخدام سر النقطة الطرفية.

X-STS-Connect-Delivery

معرّف فريد لكل حدث. استخدمه لإسقاط التكرارات.

X-STS-Connect-Attempt

رقم المحاولة.

• تجد سر العنوان تحت زر «إظهار السر» في مربع حوار «أسرار العناوين» الخاص بالخطاف.

• قارن بزمن ثابت، وارفض الطوابع الزمنية الأقدم من 5 دقائق. عقدة n8n الخاصة بنا تفعل هذا بالضبط.

• تحقق دائمًا من الجسم الخام، قبل تحليل JSON.

تحقق منه بلغتك

<?php

$secret = 'ENDPOINT_SECRET';
$timestamp = $_SERVER['HTTP_X_STS_CONNECT_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_STS_CONNECT_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');

if (abs(time() - (int) $timestamp) > 300) {
    http_response_code(401);
    exit('Stale timestamp');
}

$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);

if (! hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Bad signature');
}

// The delivery is genuine. Handle the event here.

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const SECRET = 'ENDPOINT_SECRET';

app.post('/webhooks/stsconnect', express.raw({ type: 'application/json' }), (req, res) => {
    const ts = req.get('X-STS-Connect-Timestamp') ?? '';
    const signature = req.get('X-STS-Connect-Signature') ?? '';

    if (!/^\d+$/.test(ts)) return res.sendStatus(401);

    if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
        return res.sendStatus(401);
    }

    const expected = Buffer.from(
        'sha256=' + crypto.createHmac('sha256', SECRET).update(ts + '.' + req.body).digest('hex')
    );
    const received = Buffer.from(signature);

    if (expected.length !== received.length || !crypto.timingSafeEqual(expected, received)) {
        return res.sendStatus(401);
    }

    // The delivery is genuine. Handle the event here.
    res.sendStatus(200);
});

import hmac
import time
from hashlib import sha256

from flask import Flask, request

app = Flask(__name__)
SECRET = b'ENDPOINT_SECRET'


@app.post('/webhooks/stsconnect')
def stsconnect_webhook():
    timestamp = request.headers.get('X-STS-Connect-Timestamp', '')
    signature = request.headers.get('X-STS-Connect-Signature', '')
    body = request.get_data()

    ts = int(timestamp) if timestamp and timestamp.isdigit() else 0

    if abs(time.time() - ts) > 300:
        return ('Stale timestamp', 401)

    expected = 'sha256=' + hmac.new(
        SECRET, timestamp.encode() + b'.' + body, sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        return ('Bad signature', 401)

    # The delivery is genuine. Handle the event here.
    return ('', 200)

إعادة المحاولة

• تنتظر كل محاولة الاتصال حتى 5 ثوانٍ، والاستجابة حتى 5 ثوانٍ، وبما لا يتجاوز 15 ثانية في المجموع؛ وأي استجابة 2xx تُعد نجاحًا.

• تُعاد محاولة الإرسالات التي تفشل مؤقتًا 5 مرات (6 محاولات في المجموع)، بعد نحو 1 و4 و10 و20 و25 دقيقة، وتُوقَّع كل محاولة من جديد بطابع زمني جديد. أما العناوين غير الصالحة أو غير المسموح بها فلا تُعاد محاولتها.

• تُرسل أحداث الكتابة مرة واحدة ولا تُعاد أبدًا.

• إذا استمر فشل نقطة طرفية لمدة 24 ساعة تُوقف مؤقتًا، ويتلقى المسؤولون رسالة بريد واحدة. اضغط «استئناف» لإعادة تشغيلها.

• أثناء فشل نقطة طرفية، تُحفظ حتى 1,000 حدث لمدة تصل إلى 24 ساعة.

النقاط الطرفية الرئيسية

الاستدعاءات التي ستستخدمها أكثر. المسارات نسبة إلى العنوان الأساسي والبادئة أعلاه.

• POST /contacts إنشاء جهة اتصال.
• GET /contacts/search?q= البحث في جهات الاتصال بالاسم أو البريد أو الهاتف.
• GET /conversations سرد المحادثات.
• POST /conversations فتح محادثة.
• POST /conversations/{id}/messages إرسال رسالة. يُرسل قالب واتساب في template_params مع المفاتيح name, category, language, processed_params.
• POST /conversations/{id}/toggle_status إغلاق محادثة أو إعادة فتحها.
• GET POST /conversations/{id}/labels قراءة الوسوم أو تعيينها بالجسم {"labels": [...]}.

n8n

تضيف الحزمة المجتمعية n8n-nodes-stsconnect عقدتين: STS Connect للإجراءات، وSTS Connect Trigger للأحداث. وتتحقق عقدة التشغيل من التوقيعات وتسقط الإرسالات القديمة عنك.

تحتاج نظامًا آخر؟ أخبرنا عبر واتساب