الإشعارات

ملخصات البريد الإلكتروني وwebhooks للمحادثات التي تحتاج إلى انتباه، بما في ذلك التحقق من التوقيع.

يستطيع Hearl إبلاغ فريقك فور احتياج محادثة إلى انتباه. اضبط ذلك في صفحة الإشعارات. لا يستطيع تغيير هذه الإعدادات سوى المالكين والمشرفين.

متى تُرسل الإشعارات

يفحص Hearl كل 15 دقيقة. تُدرج المحادثة عندما:

• تكون حالة المنصة لديها لا ردّ بعد أو تابع المستخدم
• يكون تقدمها لا يزال لم يبدأ
• يحكم الذكاء الاصطناعي في Hearl بأنها تتعلق بمنتجك، دون أي إجابة غير مؤكدة
• تكون أولويتها عند الحد الأدنى الذي حددته أو أعلى منه: كل شيء، أو متوسطة فأعلى، أو عالية فقط

يُرسل إشعار واحد عن كل محادثة لكل حالة. فإذا أُرسل إشعارها بحالة لا ردّ بعد ثم تابع المستخدم لاحقًا، يُرسل إشعار جديد بحالة تابع المستخدم.

البريد الإلكتروني

فعّل إرسال البريد وأضف المستلمين. اترك القائمة فارغة لإرسال البريد إلى كل أعضاء مساحة العمل. يصلح أي عنوان، مثل صندوق دعم مشترك، بحد أقصى 20 مستلمًا.

ترسل كل جولة فحص ملخصًا واحدًا يسرد حتى 10 محادثات، مع رابط إلى الباقي في صندوق الوارد. اختر الإنجليزية أو الصينية ضمن اللغة.

Webhook

أدخل نقطة النهاية. يجب أن تكون عنوان https عامًا. يتعرف Hearl على روبوتات الدردشة الشائعة من عنوانها ويرسل صيغة الرسالة التي تتوقعها:

تعرض الصفحة النوع الذي اكتشفته. يرسل إرسال اختبار عينة، وتعرض الصفحة نتيجة آخر إرسال. الطلب الذي يستغرق أكثر من 8 ثوانٍ يُعدّ انتهاءً للمهلة.

JSON عام

{
  "event": "conversations.needs_attention",
  "workspace": { "id": "org_123", "name": "Acme" },
  "text": "*2 conversations need attention* · Acme\n• [reddit] Sync stopped working after 2.3 — No reply yet <https://…>",
  "conversations": [
    {
      "id": "c_8f2a",
      "platform": "reddit",
      "product": "Acme",
      "title": "Sync stopped working after 2.3",
      "author": "some_user",
      "url": "https://www.reddit.com/r/…",
      "status": "待回复",
      "priority": "高",
      "category": "故障",
      "inbox_url": "https://hearl.org/app?c=c_8f2a"
    }
  ],
  "sent_at": "2026-11-08T09:15:00.000Z"
}

قيم platform هي x أو reddit أو hn. أما status وpriority وcategory فهي رموز ثابتة بالصينية، ليتمكن كودك من المطابقة عليها أيًّا كانت لغة مساحة عملك:

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

عند حفظ نقطة نهاية webhook ينشئ Hearl سر التوقيع لها. يمكنك إظهاره أو تدويره في صفحة الإشعارات. يحمل الطلب هذا الترويسة:

X-Hearloop-Signature: sha256=<hex>

<hex> هو HMAC-SHA256 لجسم الطلب الخام، مفتاحه سر التوقيع الخاص بك، بصيغة hex بأحرف صغيرة. احسبه على البايتات نفسها التي تلقيتها، قبل تحليل JSON، وقارن في زمن ثابت.

import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

const app = express();
const secret = process.env.HEARL_WEBHOOK_SECRET;

app.post("/hearl", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + createHmac("sha256", secret).update(req.body).digest("hex");
  const received = req.get("x-hearloop-signature") ?? "";
  const ok =
    received.length === expected.length &&
    timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!ok) return res.status(401).end();

  const payload = JSON.parse(req.body.toString("utf8"));
  console.log(payload.event, payload.conversations.length);
  res.status(200).end();
});

app.listen(3000);

import hashlib
import hmac
import json
import os

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["HEARL_WEBHOOK_SECRET"].encode()


@app.post("/hearl")
def hearl():
    body = request.get_data()
    expected = "sha256=" + hmac.new(SECRET, body, hashlib.sha256).hexdigest()
    received = request.headers.get("X-Hearloop-Signature", "")
    if not hmac.compare_digest(received, expected):
        abort(401)

    payload = json.loads(body)
    print(payload["event"], len(payload["conversations"]))
    return "", 200

أعد أي رمز حالة 2xx لتأكيد استلام الإرسال.