للمطورين
واجهة Meetowt البرمجية
اقرأ قائمة موظفي شركتك وجهات الاتصال والمهام والاجتماعات من أدواتك أنت، وأضف جهات الاتصال والمهام أو غيّرها، وأرسل رموز تحقق لمرة واحدة عبر واتساب من رقمك. يصنع مسؤول مفتاحًا، وترسله أداتك، وهذا كل الإعداد.
الواجهة البرمجية إضافة يفعّلها Meetowt للشركة عند الطلب: اكتب إلى help@meetowt.com من عنوان المسؤول لديكم. وإلى أن تُفعَّل لا يرى المسؤولون شاشة المفاتيح، ولا يجيب أي مفتاح. أما التحقق للمطورين بلا مساحة عمل فلا يحتاج إلى هذا: سجّل بوصفك مطورًا.
1. باختصار
لمساحة عملك عنوانها الخاص، مثل acme.meetowt.com. كل مسار أدناه تحت https://<your workspace>/api/v1، ويجيب بصيغة JSON، ويُفتح بمفتاح في ترويسة Authorization.
curl https://acme.meetowt.com/api/v1/me \
-H "Authorization: Bearer mwk_YOUR_KEY_HERE"
2. صنع مفتاح
يفتح مسؤول الإدارة ثم إعدادات الشركة ثم مفاتيح الواجهة البرمجية، ويضغط اصنع مفتاحًا، ويسمّيه، ويحدد ما يُسمح له به ومدة صلاحيته. يظهر المفتاح مرة واحدة مع زر للنسخ، ولا يحتفظ Meetowt إلا ببصمة لا تُعكس، فالمفتاح الضائع يُلغى ويُصنع غيره.
- يبدو المفتاح هكذا:
mwk_ثم 40 حرفًا ورقمًا. وللشركة 25 مفتاحًا عاملًا في آن واحد. - يظهر اسمه في سجل تغييرات الشركة بجانب كل ما يكتبه، بالشكل
api:<name>، ويُبلَّغ بقية المسؤولين حين يُصنع مفتاح أو يُلغى. - المفتاح يعمل باسم الشركة كلها لا باسم شخص. احفظه بعيدًا عن الدردشة والبريد والشيفرة التي يقرؤها غيرك. والإلغاء فوري.
3. المصادقة والصلاحيات
أرسل Authorization: Bearer mwk_… مع كل طلب. لا شيء آخر يفتح الواجهة البرمجية، والشركة هي صاحبة العنوان الذي سألته.
| الصلاحية | ما تسمح به |
|---|---|
people:read | قراءة قائمة الموظفين. |
contacts:read | قراءة دفتر عناوين الشركة لمن هم خارجها. |
contacts:write | إضافة جهات الاتصال وتغييرها وحذفها. |
tasks:read | قراءة كل مهام الشركة. |
tasks:write | إسناد مهمة إلى شخص مسمّى، وتغيير حالتها وأولويتها وموعدها وعنوانها. |
calendar:read | قراءة الاجتماعات التي يحضرها صانع المفتاح. |
verify:send | إرسال رمز تحقق لمرة واحدة عبر واتساب من رقم الشركة والتحقق منه، وتنبيهات واتساب، وفحص الأرقام. لا تفتح أي بيانات للشركة. |
4. المسارات
الطلب والجواب بصيغة JSON. الشيء الواحد يعود بالشكل { "data": { … } }، والقائمة بالشكل { "data": [ … ], "nextCursor": "…" }، والخطأ بالشكل { "error": "…" }. الحقل غير المعروف يُرفض باسمه ولا يُتجاهل.
| المسار | ما يفعله |
|---|---|
GET /api/v1/me | من هو هذا المفتاح. لا يحتاج إلى صلاحية. |
GET /api/v1/people | قائمة الموظفين باسم المستخدم، كما يراها زميل في دليل الشركة. |
GET /api/v1/contacts، GET /api/v1/contacts/{id} | دفتر عناوين الشركة، مع بحث ووسوم اختيارية. |
POST /api/v1/contacts، PATCH، DELETE | إضافة جهة اتصال وتغييرها وحذفها، بقواعد شاشة جهات الاتصال نفسها. |
GET /api/v1/tasks، POST، PATCH /api/v1/tasks/{id} | مهام الشركة، وإسناد مهمة، وتغيير حالتها أو أولويتها أو موعدها أو عنوانها. |
GET /api/v1/calendar/events | اجتماعات صانع المفتاح بين يومين، لا تزيد على 31 يومًا. الاجتماعات فقط، لا مواعيد أحد الخاصة. |
الأمثلة الكاملة لكل مسار في الدليل الإنجليزي؛ فالمسارات وأسماء الحقول واحدة في اللغتين.
5. الأخطاء والحدود
| الحالة | معناها |
|---|---|
| 400 | لم يُفهم الطلب: حقل غير موجود أو قيمة غير مسموحة. الجملة تقول أيها. |
| 401 | المفتاح مفقود أو خاطئ أو ملغى أو منتهٍ أو لشركة أخرى. الكلمات نفسها دائمًا، حتى لا يكشف الجواب شيئًا. |
| 403 | المفتاح حقيقي لكنه لا يملك هذه الصلاحية، أو أن الإرسال موقوف. |
| 404 | الشيء غير موجود، أو ليس لهذا المفتاح، أو الواجهة البرمجية غير مفعّلة للشركة. |
| 409 | يتعارض مع ما لدى الشركة. |
| 423 | مساحة العمل موقوفة مؤقتًا، والجملة تقول السبب. |
| 429 | طلبات كثيرة جدًا: 600 في الدقيقة لكل مفتاح، و1200 لكل مفاتيح الشركة معًا. |
| 503 | تعذّر التحقق من الطلب الآن. حاول بعد لحظة. |
هل يعمل Meetowt الآن، وهل يصل إرسال التحقق إلى ميتا؟ الجواب في صفحة حالة الخدمة.
6. التحقق من Meetowt: رموز لمرة واحدة عبر واتساب
يطلب برنامجك من Meetowt أن يرسل إلى شخص رمزًا من ستة أرقام عبر واتساب، من رقم واتساب للأعمال الخاص بشركتك، ثم يسأل هل الرمز الذي كتبه الشخص صحيح. طلبان فقط، بالمفتاح نفسه. الصلاحية هي verify:send.
- يفتح مسؤول الإدارة ثم التحقق (أو حساب المطور على
my.meetowt.com/developers)، ويضغط صِل رقم واتساب، ويلصق أربعة أشياء من حسابه للمطورين لدى ميتا: معرّف حساب واتساب للأعمال، ومعرّف رقم الهاتف، ورمز وصول دائمًا، وسرّ التطبيق. يتحقق Meetowt منها لدى ميتا قبل أن يحفظ شيئًا، ويحفظ الرمز والسرّ مشفّرين. - يصنع Meetowt رسالة الرمز بالإنجليزية والعربية والفرنسية، وتوافق ميتا على كل واحدة.
- يصنع المسؤول مفتاحًا: حقيقيًا (
mwk_live_…) أو تجريبيًا (mwk_test_…). المفتاح التجريبي لا يصل إلى ميتا أبدًا ولا يكلّف شيئًا، ورمزه دائمًا000000.
POST /api/v1/verify/send
يطلب إرسال رمز. to هو الرقم بالصيغة الدولية، وlang هي en أو ar أو fr. الرمز صالح 10 دقائق وله 5 محاولات. والرقم نفسه مرة أخرى خلال 60 ثانية يعيد الطلب نفسه دون إرسال جديد، ولا يُرسل إلى رقم واحد أكثر من 5 رموز في الساعة.
202 { "id": "vrf_Qm3xK8aT2wZr5LbN7cDp9sVe", "channel": "whatsapp", "expiresAt": "2026-11-20T18:25:00.000Z", "mode": "live" }
POST /api/v1/verify/check
هل الرمز صحيح؟ أرسل code نصًا لا رقمًا، حتى لا يضيع صفر في أوله. يُقبل الرمز الصحيح مرة واحدة، وبعدها يكون الجواب 410.
200 { "valid": true }
200 { "valid": false, "triesLeft": 3 }
410 { "error": "that code has expired or been used up — send a new one" }
GET /api/v1/verify/{id}
أين وصل الطلب: queued أو sent أو delivered أو read أو failed أو approved أو expired. لا يُعاد الرقم أبدًا، بل آخر ثلاثة أرقام منه فقط.
تحديثات التسليم إلى نظامك
ضع عنوان https في شاشة التحقق، فيرسل Meetowt إليه كل تغيّر في حالة الطلب، موقّعًا بترويسة X-Meetowt-Signature: t=<time>,v1=<signature>. التوقيع هو HMAC-SHA256 للوقت ثم نقطة ثم الجسم كما وصل، بالسرّ الذي يظهر لك مرة واحدة. ارفض أي تحديث أقدم من خمس دقائق، وقد يصل التحديث أكثر من مرة، فاحذف المكرر. لا يحمل الجسم الرقم ولا الرمز أبدًا.
الثمن
التحقق مجاني خلال الوصول المبكر، ورموز الاختبار لا تُحاسَب أبدًا. وبعده الخطة 0.015 دولار عن كل تحقق ناجح فقط، إضافة إلى ما تحاسبك به ميتا على الرسالة في حسابك أنت. التفاصيل في صفحة التحقق من Meetowt.
7. مفتاح لكل عميل من عملائك
لشركات البرمجيات التي ترسل رموزًا لعملائها. في شاشة التحقق تحت العملاء سمِّ كل عميل، فيأخذ رقمًا، ويكون له:
- مفاتيحه الخاصة: مفتاح العميل يرسل باسمه، ولا يقرأ ولا يتحقق إلا من طلبات هذا العميل. سؤال مفتاح العميل الأول عن طلب العميل الثاني يجاب بالخطأ 404، تمامًا كمعرّف لم يصنعه أحد، والعكس كذلك، ومفتاح الحساب نفسه لا يقرأ طلبات العملاء.
- مفتاح تشغيله الخاص: العميل الموقوف يُرفض بالخطأ 403 بجملة تقول ذلك، وإيقاف الحساب كله يوقف كل العملاء.
- حدّه اليومي ودوله الخاصة، ويبقى حدّ الحساب ساريًا عليهم جميعًا معًا.
- عنوان تحديثاته الخاص، ومن دونه تذهب تحديثاته إلى عنوان الحساب، وكل تحديث يحمل رقم العميل في
"client". - إن أراد، رقم واتساب خاص به بالتفاصيل الأربع نفسها، ومن دونه تخرج رموزه من رقم الحساب.
- استخدامه وسجله: يمكن قصرهما على عميل واحد، وملف
CSVيحمل رقم العميل واسمه في كل سطر.
8. تنبيهات واتساب غير الرموز
بالمفاتيح نفسها ترسل قوالب الخدمة المعتمدة الخاصة بشركتك (تحديثات الطلبات والتذكيرات والإيصالات) من رقمك، بالسجل والحالات وتحديثات التسليم نفسها، وبقواعد الإرسال نفسها. لا تُرسل قوالب التسويق أبدًا: القالب الذي صنّفته ميتا في غير فئة الخدمة يُرفض بالخطأ 403، وغير المعتمد بالخطأ 409. اضغط حدّث من ميتا في شاشة التحقق تحت تنبيهات واتساب لتظهر قوالبك.
curl -X POST https://my.meetowt.com/api/v1/whatsapp/send \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "+201001234567", "template": "order_shipped", "lang": "en_US", "params": ["A-1042", "Thursday"]}'
تُقرأ حالة التنبيه من GET /api/v1/whatsapp/{id}. الكلمات التي تملأ القالب تنتظر إرسالها مشفّرة وتُحذف بعد جواب ميتا، ولا يحتفظ Meetowt إلا باسم القالب. لم يُحدَّد سعر للتنبيهات بعد، وهي مجانية خلال الوصول المبكر، وتحاسبك ميتا على كل رسالة في حسابك.
9. فحص رقم
curl -X POST https://my.meetowt.com/api/v1/lookup \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"number": "+201001234567"}'
200 { "valid": true, "possible": true, "e164": "+201001234567", "country": "EG", "callingCode": "20",
"type": "mobile", "national": "010 01234567", "international": "+20 10 01234567" }
هل الرقم دولي صحيح، وما دولته، وما نوعه: محمول أو أرضي أو مجاني أو غير ذلك. مجاني.
يُحسب على خادم Meetowt نفسه من جداول الترقيم المنشورة، ولا يُسأل أحد، لا ميتا ولا شركة اتصالات. لذلك لا يعرف هل للرقم حساب واتساب، ولا هل الخط يعمل أو ما زال لصاحبه، ولا أي شركة تحمله الآن. «صحيح» تعني أن الأرقام توافق خطة الترقيم في تلك الدولة لا أكثر. ولا يُحفظ شيء، ولا الرقم نفسه.
10. أمثلة الشيفرة
ضع مفتاحك مكان YOUR_KEY. كل مثال هنا يُفحص مقابل المسارات الحقيقية، وتُشغَّل أمثلة فحص التوقيع، قبل نشر هذه الصفحة.
أرسل رمزًا وتحقق منه
curl
# 1. Send a code
curl -X POST https://my.meetowt.com/api/v1/verify/send \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "+201001234567", "lang": "en"}'
# 2. Check what the person typed, with the id the send answered
curl -X POST https://my.meetowt.com/api/v1/verify/check \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"id": "vrf_...", "code": "000000"}'
Node.js
// Node.js 18 or later: fetch is built in.
const KEY = "YOUR_KEY";
const BASE = "https://my.meetowt.com/api/v1/verify/";
async function call(path, body) {
const res = await fetch(BASE + path, {
method: "POST",
headers: { Authorization: "Bearer " + KEY, "Content-Type": "application/json" },
body,
});
return { status: res.status, body: await res.json() };
}
const sent = await call("send", JSON.stringify({"to": "+201001234567", "lang": "en"}));
// ...the person types the code they were sent...
const checked = await call("check", JSON.stringify({ id: sent.body.id, code: "000000" }));
console.log(checked.status === 200 && checked.body.valid);
Python
import requests
KEY = "YOUR_KEY"
BASE = "https://my.meetowt.com/api/v1/verify/"
HEADERS = {"Authorization": f"Bearer {KEY}"}
sent = requests.post(BASE + "send", json={"to": "+201001234567", "lang": "en"}, headers=HEADERS).json()
# ...the person types the code they were sent...
checked = requests.post(BASE + "check", json={"id": sent["id"], "code": "000000"}, headers=HEADERS)
print(checked.status_code == 200 and checked.json()["valid"])
PHP
<?php
const KEY = 'YOUR_KEY';
const BASE = 'https://my.meetowt.com/api/v1/verify/';
function call(string $path, string $body): array {
$ch = curl_init(BASE . $path);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $body,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . KEY, 'Content-Type: application/json'],
]);
$answer = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
return [$status, $answer];
}
[$status, $sent] = call('send', '{"to": "+201001234567", "lang": "en"}');
// ...the person types the code they were sent...
[$status, $checked] = call('check', json_encode(['id' => $sent['id'], 'code' => '000000']));
var_dump($status === 200 && $checked['valid']);
C#
// .NET 7 or later (C# 11 raw strings).
using System.Net.Http.Json;
using System.Text;
using System.Text.Json;
var http = new HttpClient { BaseAddress = new Uri("https://my.meetowt.com/api/v1/verify/") };
http.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_KEY");
var send = await http.PostAsync("send", new StringContent("""{"to": "+201001234567", "lang": "en"}""", Encoding.UTF8, "application/json"));
var sent = await send.Content.ReadFromJsonAsync<JsonElement>();
var id = sent.GetProperty("id").GetString();
// ...the person types the code they were sent...
var check = await http.PostAsJsonAsync("check", new { id, code = "000000" });
var checkedRight = check.IsSuccessStatusCode && (await check.Content.ReadFromJsonAsync<JsonElement>()).GetProperty("valid").GetBoolean();
Console.WriteLine(checkedRight);
Java
// Java 15 or later (text blocks); any JSON library reads the answers.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class SendCode {
static final String KEY = "YOUR_KEY";
static final String BASE = "https://my.meetowt.com/api/v1/verify/";
static final HttpClient HTTP = HttpClient.newHttpClient();
static HttpResponse<String> call(String path, String body) throws Exception {
HttpRequest req = HttpRequest.newBuilder(URI.create(BASE + path))
.header("Authorization", "Bearer " + KEY)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
return HTTP.send(req, HttpResponse.BodyHandlers.ofString());
}
public static void main(String[] args) throws Exception {
HttpResponse<String> sent = call("send", """
{"to": "+201001234567", "lang": "en"}
""");
System.out.println(sent.body()); // {"id": "vrf_...", ...}: keep the id
// ...the person types the code they were sent...
String id = args[0];
HttpResponse<String> checked = call("check", "{\"id\": \"" + id + "\", \"code\": \"000000\"}");
System.out.println(checked.statusCode() + " " + checked.body());
}
}
تحقق من توقيع تحديث تسليم
استخدم الجسم كما وصل تمامًا، قبل أن يحلّله أي شيء.
curl
# In a shell script, for trying it out: SECRET, HEADER (the X-Meetowt-Signature value) and BODY (the raw body) are yours.
# A shell cannot compare two strings in constant time, so it compares HMACs of both under a fresh random key: how long that takes says
# nothing about the signature. For a real server, use one of the other samples.
T=$(printf '%s' "$HEADER" | sed -n 's/.*t=\([0-9]\{1,12\}\).*/\1/p')
V1=$(printf '%s' "$HEADER" | sed -n 's/.*v1=\([0-9a-f]\{64\}\).*/\1/p')
[ -n "$T" ] && [ -n "$V1" ] || { echo "refuse it"; exit 1; }
WANT=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)
R=$(openssl rand -hex 32)
A=$(printf '%s' "$WANT" | openssl dgst -sha256 -hmac "$R" -r | cut -d' ' -f1)
B=$(printf '%s' "$V1" | openssl dgst -sha256 -hmac "$R" -r | cut -d' ' -f1)
AGE=$(( $(date +%s) - T ))
[ "$A" = "$B" ] && [ "$AGE" -le 300 ] && [ "$AGE" -ge -300 ] && echo "genuine" || echo "refuse it"
Node.js
const crypto = require("node:crypto");
// header: the X-Meetowt-Signature value; rawBody: the body exactly as it arrived (a string); secret: your signing secret.
function genuine(header, rawBody, secret, now = Math.floor(Date.now() / 1000)) {
const parts = Object.fromEntries(String(header).split(",").map((p) => p.trim().split("=", 2)));
if (!/^\d+$/.test(parts.t ?? "") || !/^[0-9a-f]{64}$/.test(parts.v1 ?? "")) return false;
if (Math.abs(now - Number(parts.t)) > 300) return false;
const want = crypto.createHmac("sha256", secret).update(parts.t + "." + rawBody).digest();
return crypto.timingSafeEqual(want, Buffer.from(parts.v1, "hex"));
}
Python
import hashlib, hmac, re, time
# header: the X-Meetowt-Signature value; raw_body: the body exactly as it arrived (str); secret: your signing secret.
# A malformed header is answered False, never an exception.
def genuine(header, raw_body, secret, now=None):
now = int(time.time()) if now is None else now
parts = dict(p.strip().split("=", 1) for p in str(header).split(",") if "=" in p)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not re.fullmatch(r"[0-9]{1,12}", t) or not re.fullmatch(r"[0-9a-f]{64}", v1) or abs(now - int(t)) > 300:
return False
want = hmac.new(secret.encode(), f"{t}.{raw_body}".encode(), hashlib.sha256).hexdigest()
return hmac.compare_digest(want, v1)
PHP
<?php
// $header: the X-Meetowt-Signature value; $rawBody: file_get_contents('php://input'); $secret: your signing secret.
function genuine(string $header, string $rawBody, string $secret): bool {
$parts = [];
foreach (explode(',', $header) as $p) {
[$k, $v] = array_pad(explode('=', trim($p), 2), 2, '');
$parts[$k] = $v;
}
$t = $parts['t'] ?? '';
$v1 = $parts['v1'] ?? '';
if (!ctype_digit($t) || strlen($v1) !== 64 || abs(time() - (int) $t) > 300) return false;
$want = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
return hash_equals($want, $v1);
}
C#
using System.Security.Cryptography;
using System.Text;
using System.Text.RegularExpressions;
// header: the X-Meetowt-Signature value; rawBody: the body exactly as it arrived; secret: your signing secret.
// A malformed header is answered false, never an exception.
static bool Genuine(string header, string rawBody, string secret)
{
string? t = null, v1 = null;
foreach (var p in (header ?? "").Split(','))
{
var kv = p.Trim().Split('=', 2);
if (kv.Length == 2 && kv[0] == "t") t = kv[1];
if (kv.Length == 2 && kv[0] == "v1") v1 = kv[1];
}
if (t == null || !Regex.IsMatch(t, "^[0-9]{1,12}$") || !long.TryParse(t, out var seconds)) return false;
if (v1 == null || !Regex.IsMatch(v1, "^[0-9a-f]{64}$")) return false;
if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - seconds) > 300) return false;
var want = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), Encoding.UTF8.GetBytes(t + "." + rawBody));
return CryptographicOperations.FixedTimeEquals(want, Convert.FromHexString(v1));
}
Java
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
// header: the X-Meetowt-Signature value; rawBody: the body exactly as it arrived; secret: your signing secret. Java 17 or later.
// A malformed header is answered false, never an exception.
static boolean genuine(String header, String rawBody, String secret) throws Exception {
String t = null, v1 = null;
for (String p : String.valueOf(header).split(",")) {
String[] kv = p.trim().split("=", 2);
if (kv.length == 2 && kv[0].equals("t")) t = kv[1];
if (kv.length == 2 && kv[0].equals("v1")) v1 = kv[1];
}
if (t == null || v1 == null || !t.matches("[0-9]{1,12}") || !v1.matches("[0-9a-f]{64}")) return false;
if (Math.abs(System.currentTimeMillis() / 1000 - Long.parseLong(t)) > 300) return false;
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
byte[] want = mac.doFinal((t + "." + rawBody).getBytes(StandardCharsets.UTF_8));
return MessageDigest.isEqual(want, HexFormat.of().parseHex(v1));
}