مرحباً بك في وثائق WAAPI

واجهة WAAPI تمنحك القدرة على دمج واتساب في تطبيقاتك بسهولة. هذه الوثائق ستساعدك على البدء، سواء كنت تريد إرسال أول رسالة لك أو تبني نظاماً معقداً للمحادثات الآلية.

المصادقة (Authentication)

ملاحظة: يجب إدراج API Key و Auth Key في كل العمليات.

قم بتسجيل الدخول لرؤية مفاتيح الـ API الخاصة بك هنا.

تسجيل الدخول

حزمة Laravel (WAAPI Laravel Package)

توفر هذه الحزمة واجهة API بسيطة ومعبرة للتفاعل مع خدمة WAAPI (WhatsApp API) داخل تطبيق Laravel بشكل سلس وسريع.

المميزات

إرسال الرسائل النصية و OTP.
واجهة برمجية (API) سلسة ومعبرة.
تسجيل تلقائي لمسار الـ Webhook.
معالجة بيانات الـ Webhook الواردة.
تكامل مع Webhook.site للتنقيح (Debugging).

عرض على GitHub

التثبيت (Installation)

composer require octopusteam/waapi-laravel

قم بنشر ملف الإعدادات:

php artisan vendor:publish --provider="OctopusTeam\Waapi\WaapiServiceProvider"

الإعدادات (Configuration)

قم بتحديث ملف .env الخاص بك بالبيانات التالية:

WAAPI_APP_URL=https://waapi.octopusteam.net/api/v1/message/send
WAAPI_APP_KEY=your_app_key
WAAPI_AUTH_KEY=your_auth_key
WAAPI_WEBHOOK_SITE_TOKEN=your_webhook_site_token
WAAPI_UPDATE_DEVICE_WEBHOOK=your_device_uuid_for_webhook_update

الاستخدام (Usage)

إرسال الرسائل

use OctopusTeam\Waapi\Facades\Waapi;

// Send a simple text message
$response = Waapi::sendMessage('1234567890', 'Hello, world!');

// Send an OTP
$otp = Waapi::generateOtp();
$response = Waapi::sendOtp('1234567890', $otp);

Webhook Handling

يمكن للحزمة تسجيل مسار Webhook تلقائياً. لتفعيل ذلك تأكد من الإعدادات في config/waapi.php:

'webhook' => [
    'enabled' => true,
    'auto_register' => true,
],

POST

إرسال رسالة نصية

Endpoint بسيط لإرسال رسائل نصية مباشرة إلى أي رقم واتساب.

curl --location --request POST 'https://waapi.octopusteam.net/api/create-message' \
--form 'appkey="YOUR_APP_KEY"' \
--form 'authkey="YOUR_AUTH_KEY"' \
--form 'to="2010xxxxxxxx"' \
--form 'message="Hello from WAAPI!"'

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://waapi.octopusteam.net/api/create-message',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array(
    'appkey' => 'YOUR_APP_KEY',
    'authkey' => 'YOUR_AUTH_KEY',
    'to' => '2010xxxxxxxx',
    'message' => 'Hello from WAAPI!',
    'sandbox' => 'false'
  ),
));

$response = curl_exec($curl);
curl_close($curl);
echo $response;

use OctopusTeam\Waapi\Facades\Waapi;

// Send a simple text message
$response = Waapi::sendMessage('2010xxxxxxxx', 'Hello from WAAPI!');

// Send an OTP
// $otp = Waapi::generateOtp();
// $response = Waapi::sendOtp('2010xxxxxxxx', $otp);

const axios = require('axios');
const FormData = require('form-data');
let data = new FormData();
data.append('appkey', 'YOUR_APP_KEY');
data.append('authkey', 'YOUR_AUTH_KEY');
data.append('to', '2010xxxxxxxx');
data.append('message', 'Hello from WAAPI!');

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://waapi.octopusteam.net/api/create-message',
  headers: {
    ...data.getHeaders()
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var client = new HttpClient();
        var request = new HttpRequestMessage(HttpMethod.Post, "https://waapi.octopusteam.net/api/create-message");
        var content = new MultipartFormDataContent();
        content.Add(new StringContent("YOUR_APP_KEY"), "appkey");
        content.Add(new StringContent("YOUR_AUTH_KEY"), "authkey");
        content.Add(new StringContent("2010xxxxxxxx"), "to");
        content.Add(new StringContent("Hello from WAAPI!"), "message");
        request.Content = content;
        var response = await client.SendAsync(request);
        response.EnsureSuccessStatusCode();
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

import requests

url = "https://waapi.octopusteam.net/api/create-message"

payload = {
    'appkey': 'YOUR_APP_KEY',
    'authkey': 'YOUR_AUTH_KEY',
    'to': '2010xxxxxxxx',
    'message': 'Hello from WAAPI!'
}
files = []
headers = {}

response = requests.post(url, headers=headers, data=payload, files=files)

print(response.text)

package main

import (
  "fmt"
  "bytes"
  "mime/multipart"
  "net/http"
  "io/ioutil"
)

func main() {
  url := "https://waapi.octopusteam.net/api/create-message"
  method := "POST"

  payload := &bytes.Buffer{}
  writer := multipart.NewWriter(payload)
  _ = writer.WriteField("appkey", "YOUR_APP_KEY")
  _ = writer.WriteField("authkey", "YOUR_AUTH_KEY")
  _ = writer.WriteField("to", "2010xxxxxxxx")
  _ = writer.WriteField("message", "Hello from WAAPI!")
  err := writer.Close()
  if err != nil {
    fmt.Println(err)
    return
  }

  client := &http.Client {}
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Set("Content-Type", writer.FormDataContentType())
  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

POST

إرسال وسائط (صور، ملفات)

إرسال ملفات PDF، صور، أو مستندات عبر رابط مباشر.

curl --location --request POST 'https://waapi.octopusteam.net/api/create-message' \
--form 'appkey="YOUR_APP_KEY"' \
--form 'authkey="YOUR_AUTH_KEY"' \
--form 'to="2010xxxxxxxx"' \
--form 'message="Here is your invoice"' \
--form 'file="https://example.com/invoice.pdf"'

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://waapi.octopusteam.net/api/create-message',
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => array(
    'appkey' => 'YOUR_APP_KEY',
    'authkey' => 'YOUR_AUTH_KEY',
    'to' => '2010xxxxxxxx',
    'message' => 'Here is your invoice',
    'file' => 'https://example.com/invoice.pdf'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

use OctopusTeam\Waapi\Facades\Waapi;

$response = Waapi::sendMessage('2010xxxxxxxx', 'Here is your invoice', ['file' => 'https://example.com/invoice.pdf']);

const axios = require('axios');
const FormData = require('form-data');
let data = new FormData();
data.append('appkey', 'YOUR_APP_KEY');
data.append('authkey', 'YOUR_AUTH_KEY');
data.append('to', '2010xxxxxxxx');
data.append('message', 'Here is your invoice');
data.append('file', 'https://example.com/invoice.pdf');

axios.post('https://waapi.octopusteam.net/api/create-message', data)
.then(res => console.log(res.data))
.catch(err => console.error(err));

var client = new HttpClient();
var content = new MultipartFormDataContent();
content.Add(new StringContent("YOUR_APP_KEY"), "appkey");
content.Add(new StringContent("YOUR_AUTH_KEY"), "authkey");
content.Add(new StringContent("2010xxxxxxxx"), "to");
content.Add(new StringContent("Here is your invoice"), "message");
content.Add(new StringContent("https://example.com/invoice.pdf"), "file");

var response = await client.PostAsync("https://waapi.octopusteam.net/api/create-message", content);
Console.WriteLine(await response.Content.ReadAsStringAsync());

import requests

data = {
    'appkey': 'YOUR_APP_KEY',
    'authkey': 'YOUR_AUTH_KEY',
    'to': '2010xxxxxxxx',
    'message': 'Here is your invoice',
    'file': 'https://example.com/invoice.pdf'
}
response = requests.post('https://waapi.octopusteam.net/api/create-message', data=data)
print(response.text)

// ... Setup multipart writer ...
_ = writer.WriteField("file", "https://example.com/invoice.pdf")
// ... Send request ...

POST

إرسال قالب (Template)

إرسال قوالب واتساب المعتمدة مع متغيرات ديناميكية.

curl --location --request POST 'https://waapi.octopusteam.net/api/create-message' \
--form 'appkey="YOUR_APP_KEY"' \
--form 'authkey="YOUR_AUTH_KEY"' \
--form 'to="2010xxxxxxxx"' \
--form 'template_id="TEMPLATE_ID"' \
--form 'variables[{1}]="John"' \
--form 'variables[{2}]="Order #123"'

// ... Setup ...
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://waapi.octopusteam.net/api/create-message',
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => array(
    'appkey' => 'YOUR_APP_KEY',
    'authkey' => 'YOUR_AUTH_KEY',
    'to' => '2010xxxxxxxx',
    'template_id' => 'TEMPLATE_ID',
    'variables[{1}]' => 'John',
    'variables[{2}]' => 'Order #123'
  ),
));
// ... Execute ...

use OctopusTeam\Waapi\Facades\Waapi;

$response = Waapi::sendMessage(
    '2010xxxxxxxx',
    null,
    ['template_id' => 'TEMPLATE_ID', 'variables' => ['{1}' => 'John', '{2}' => 'Order #123']]
);

const axios = require('axios');
const FormData = require('form-data');
let data = new FormData();
// ... App/Auth Key/To ...
data.append('template_id', 'TEMPLATE_ID');
data.append('variables[{1}]', 'John');
data.append('variables[{2}]', 'Order #123');

axios.post('https://waapi.octopusteam.net/api/create-message', data)
.then(res => console.log(res.data))
.catch(err => console.error(err));

// ... Client setup ...
var content = new MultipartFormDataContent();
// ... App Key, Auth Key, To ...
content.Add(new StringContent("TEMPLATE_ID"), "template_id");
content.Add(new StringContent("John"), "variables[{1}]");
content.Add(new StringContent("Order #123"), "variables[{2}]");

var response = await client.PostAsync("https://waapi.octopusteam.net/api/create-message", content);
// ...

import requests
data = {
    # ... App Key, Auth Key, To ...
    'template_id': 'TEMPLATE_ID',
    'variables[{1}]': 'John',
    'variables[{2}]': 'Order #123'
}
response = requests.post('https://waapi.octopusteam.net/api/create-message', data=data)
print(response.text)

// ... Setup multipart writer ...
_ = writer.WriteField("template_id", "TEMPLATE_ID")
_ = writer.WriteField("variables[{1}]", "John")
_ = writer.WriteField("variables[{2}]", "Order #123")
// ... Send request ...

POST

إرسال ملصق (Sticker)

إرسال ملصقات واتساب ثابتة أو متحركة عبر رابط مباشر.

curl --location --request POST 'https://waapi.octopusteam.net/api/send-sticker' \
--form 'appkey="YOUR_APP_KEY"' \
--form 'authkey="YOUR_AUTH_KEY"' \
--form 'to="2010xxxxxxxx"' \
--form 'url="https://example.com/sticker.webp"'

POST

إرسال ملاحظة صوتية (Voice Note)

إرسال ملف صوتي ليظهر كأنه مسجل من الميكروفون (PTT).

curl --location --request POST 'https://waapi.octopusteam.net/api/send-voice' \
--form 'appkey="YOUR_APP_KEY"' \
--form 'authkey="YOUR_AUTH_KEY"' \
--form 'to="2010xxxxxxxx"' \
--form 'url="https://example.com/voice.mp3"'

POST

إرسال موقع (Location)

مشاركة موقع جغرافي محدد على الخريطة.

curl --location --request POST 'https://waapi.octopusteam.net/api/send-location' \
--form 'appkey="YOUR_APP_KEY"' \
--form 'authkey="YOUR_AUTH_KEY"' \
--form 'to="2010xxxxxxxx"' \
--form 'latitude="30.0444"' \
--form 'longitude="31.2357"'

POST

إرسال جهة اتصال (Contact)

مشاركة بطاقة جهة اتصال (VCard).

curl --location --request POST 'https://waapi.octopusteam.net/api/send-contact' \
--form 'appkey="YOUR_APP_KEY"' \
--form 'authkey="YOUR_AUTH_KEY"' \
--form 'to="2010xxxxxxxx"' \
--form 'contact[name]="John Doe"' \
--form 'contact[number]="2010xxxxxxxx"' \
--form 'contact[organization]="Octopus Team"'

POST

الحصول على حالة الجهاز

التحقق من حالة اتصال الجهاز بالخادم باستخدام معرف الجهاز.

curl --location --request POST 'https://waapi.octopusteam.net/api/get-status' \
--form 'device_id="DEVICE_ID"' \
--form 'authkey="YOUR_AUTH_KEY"'

POST

الحصول على رمز QR

الحصول على رمز الاستجابة السريعة (QR Code) لربط الجهاز.

curl --location --request POST 'https://waapi.octopusteam.net/api/get-qr' \
--form 'device_id="DEVICE_ID"' \
--form 'authkey="YOUR_AUTH_KEY"'

البارامترات (Parameters)

الاسم	النوع	مطلوب؟	الوصف
appkey	string	نعم	مفتاح التطبيق الخاص بك
authkey	string	نعم	مفتاح المصادقة الخاص بالمستخدم
to	number	نعم	رقم الواتساب المستلم بالصيغة الدولية (مثال: 2010xxxxxx)
message	string	مشروط	نص الرسالة (مطلوب في حالة عدم استخدام قالب)
file	url	لا	رابط مباشر للملف المرفق (PDF, JPG, PNG, etc...)
template_id	string	لا	معرف القالب (Template ID) في حالة إرسال قالب
variables	array	لا	مصفوفة المتغيرات للقالب. المثال: `variables[{1}]`

نموذج الاستجابة (Response)

{
    "message_status": "Success",
    "data": {
        "from": "SENDER_NUMBER",
        "to": "RECEIVER_NUMBER",
        "status_code": 200,
        "message_id": "wamid.HBgLM..."
    }
}

أكواد الخطأ (Error Codes)

الكود	المعنى	الوصف
401	Unauthorized	مفتاح التطبيق (App Key) أو مفتاح المصادقة (Auth Key) غير صحيح.
403	Forbidden	حسابك غير نشط أو ليس لديك رصيد كافٍ.
404	Not Found	المسار المطلوب غير موجود.
422	Validation Error	خطأ في البيانات المرسلة (مثل رقم هاتف غير صحيح أو حقل مفقود).
500	Server Error	خطأ داخلي في الخادم، يرجى المحاولة لاحقاً.

هيكلية بيانات Webhook (Incoming Message)

عند استقبال رسالة جديدة، سيقوم النظام بإرسال طلب POST إلى رابط الـ Webhook الخاص بك يحتوي على البيانات التالية:

{
    "event": "message",
    "instanceId": "12345",
    "data": {
        "id": "false_1234567890@c.us_3EB0...",
        "from": "1234567890@c.us",
        "to": "0987654321@c.us",
        "body": "Hello World",
        "type": "chat",
        "timestamp": 1672531200,
        "notifyName": "John Doe",
        "isGroupMsg": false
    }
}