API
الرسائل القصيرة والمكالمات
أرسل رسائل SMS واطلب مكالمات من الذكاء الاصطناعي عبر خط هاتف وكيلك
# الرسائل القصيرة والمكالمات > أرسل رسائل SMS واطلب مكالمات من الذكاء الاصطناعي عبر خط هاتف وكيلك - الصفحة: https://tbit.app/ar/docs/api/sms-calls - عنوان URL الأساسي: `https://rest-api.tbit.app/v1` - المصادقة: ترويسة `X-API-Key` تحمل مفتاحك في كل طلب (تقرأه الأمثلة من متغير البيئة `TBIT_API_KEY`) ## نظرة عامة كلاهما يخرج عبر خط هاتف وكيلك (الذي تشتريه من الإضافات › خط الهاتف) ويستهلك طاقة من خطتك. تُحفظ كل رسالة SMS مرسلة في محادثة جهة الاتصال في TBit (وتُنشأ جهة الاتصال إن لم تكن موجودة)، وتظهر الرسائل التي تصلك في صندوق الوارد عبر قناة SMS. ## نقاط النهاية | الطريقة | المسار | الوصف | | --- | --- | --- | | `POST` | `/v1/sms` | إرسال رسالة SMS | | `POST` | `/v1/calls` | جعل الذكاء الاصطناعي يتصل برقم | ## المتطلبات - خط هاتف نشط لدى الوكيل المالك لمفتاح API. - طاقة كافية: يُتحقق منها قبل الإرسال أو الاتصال، وإن لم تكفِ لا يخرج شيء (402). - رسائل SMS إلى أرقام +1 (الولايات المتحدة وكندا وبورتوريكو…) تتطلب تسجيل 10DLC للنشاط التجاري؛ وحتى ذلك الحين تعيد 422. لكل رقم قدراته: إذا كان الخط لا يرسل SMS إلى تلك الوجهة، تتضمن الاستجابة سبب المشغّل (502). ## إرسال رسالة SMS الحقول: to (رقم بصيغة E.164، مع + ورمز الدولة)، وtext (حتى 1,530 حرفًا)، وfrom (اختياري: أحد خطوط الوكيل بصيغة E.164، أو مُرسِل أبجدي رقمي من 1 إلى 11 حرفًا/رقمًا مثل "MiTienda"، لا يمكن الرد عليه ولا يصلح للأرقام +1؛ وبدونه، يُستخدم أقدم خط). تُخبر الاستجابة بعدد الأجزاء التي استُخدمت ومقدار الطاقة التي استُهلكت. `POST /v1/sms` ```bash curl -X POST "https://rest-api.tbit.app/v1/sms" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "+573001234567", "text": "Hola Ana, tu pedido #1042 sale hoy." }' ``` الاستجابة: ```json { "id": "40319a3e-7e2c-4f4e-9b0e-2c1d5f8a9b10", "from": "+17869572575", "to": "+573001234567", "parts": 1, "energy": 3, "contact_id": "6ac9f1e6af6d42a269f21b15", "message_id": "6ac9f2a1af6d42a269f21c02" } ``` ## طاقة الرسائل القصيرة | الحالة | الطاقة لكل جزء | | --- | --- | | رسالة إلى رقم +1 | 1 (يتطلب 10DLC) | | رسالة إلى أي دولة أخرى | `3` | | رسالة مستلمة | `1` | تُرسل الرسالة الطويلة في عدة أجزاء: حتى 160 حرفًا جزء واحد؛ ومع الرموز التعبيرية أو الأحرف خارج أبجدية GSM حتى 70. وما زاد يُحتسب لكل جزء. ## طلب مكالمة يتصل الذكاء الاصطناعي لوكيلك بالرقم بالهدف الذي تحدده في reason (حتى 2000 حرف). الحقول: to (E.164)، وreason، وcontact_id (اختياري: جهة الاتصال في TBit؛ وبدونه يُبحث عنها بالرقم وتُنشأ إن لم توجد). الاستجابة 202: تم طلب المكالمة. تكلف 6 من الطاقة لكل دقيقة وتُحتسب عند انتهائها؛ حاليًا يمكن الاتصال بأرقام كولومبيا فقط. وضع الإشعار: إذا أرسلت message (حتى 1.000 حرف) بدلًا من reason، فإن المكالمة تُبلغ فقط. تقول الـ AI ذلك النص كما هو بعد ثوانٍ من الرد (دون انتظار تحدث الشخص)، وتودع وتغلق؛ لا تتحاور ولا تجيب على الأسئلة. مع message، يكون reason اختياريًا ويُستخدم كسياق. تجري المكالمة عبر خط وكيلك وتُحتسب بنفس الطريقة: 6 من الطاقة لكل دقيقة بدأت. `POST /v1/calls` ```bash curl -X POST "https://rest-api.tbit.app/v1/calls" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "+573001234567", "reason": "Confirmar la cita de mañana a las 10:00 y ofrecer cambiarla si no puede." }' ``` الاستجابة: ```json { "call_id": "6ac9f3b7af6d42a269f21c10", "provider_call_id": "conv_8f2k1x", "from": "+576019190351", "to": "+573001234567", "contact_id": "6ac9f1e6af6d42a269f21b15", "status": "requested" } ``` `POST /v1/calls` ```bash curl -X POST "https://rest-api.tbit.app/v1/calls" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "+573001234567", "message": "Tu pago de 250 USD fue aprobado. Ya puedes verlo en tu cuenta." }' ``` ## الرسائل النصية التي تستقبلها تظهر الرسائل النصية التي تُكتب إلى خطك في صندوق وارد TBit كمحادثة عبر SMS. لا تجيب عليها الـ AI. كل واحدة تستهلك 1 من الطاقة لكل جزء. ## الحدود بالإضافة إلى الحد العام البالغ 100 طلب في الدقيقة، يقبل كل من هذه الـ endpoints حتى 30 في الدقيقة لكل وكيل. ## الأخطاء | الحالة | الرمز | الوصف | | --- | --- | --- | | `409` | `NO_PHONE_LINE` | الوكيل ليس لديه خط هاتفي نشط | | `422` | `DESTINATION_NOT_ALLOWED` | الوجهة غير مفعّلة بعد (أرقام +1 تتطلب 10DLC) | | `402` | `INSUFFICIENT_ENERGY` | الطاقة غير كافية؛ لم يُرسل ولم يُتصل | | `502` | `PROVIDER_ERROR` | رفض المشغل الإرسال أو المكالمة؛ يحمل message سببه |كلاهما يخرج عبر خط هاتف وكيلك (الذي تشتريه من الإضافات › خط الهاتف) ويستهلك طاقة من خطتك. تُحفظ كل رسالة SMS مرسلة في محادثة جهة الاتصال في TBit (وتُنشأ جهة الاتصال إن لم تكن موجودة)، وتظهر الرسائل التي تصلك في صندوق الوارد عبر قناة SMS.
| الطريقة | المسار | الوصف |
|---|---|---|
| POST | /v1/sms | إرسال رسالة SMS |
| POST | /v1/calls | جعل الذكاء الاصطناعي يتصل برقم |
- خط هاتف نشط لدى الوكيل المالك لمفتاح API.
- طاقة كافية: يُتحقق منها قبل الإرسال أو الاتصال، وإن لم تكفِ لا يخرج شيء (402).
- رسائل SMS إلى أرقام +1 (الولايات المتحدة وكندا وبورتوريكو…) تتطلب تسجيل 10DLC للنشاط التجاري؛ وحتى ذلك الحين تعيد 422. لكل رقم قدراته: إذا كان الخط لا يرسل SMS إلى تلك الوجهة، تتضمن الاستجابة سبب المشغّل (502).
الحقول: to (رقم بصيغة E.164، مع + ورمز الدولة)، وtext (حتى 1,530 حرفًا)، وfrom (اختياري: أحد خطوط الوكيل بصيغة E.164، أو مُرسِل أبجدي رقمي من 1 إلى 11 حرفًا/رقمًا مثل "MiTienda"، لا يمكن الرد عليه ولا يصلح للأرقام +1؛ وبدونه، يُستخدم أقدم خط). تُخبر الاستجابة بعدد الأجزاء التي استُخدمت ومقدار الطاقة التي استُهلكت.
/v1/smscurl -X POST "https://rest-api.tbit.app/v1/sms" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+573001234567",
"text": "Hola Ana, tu pedido #1042 sale hoy."
}'const response = await fetch('https://rest-api.tbit.app/v1/sms', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '+573001234567',
text: 'Hola Ana, tu pedido #1042 sale hoy.',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/sms',
{
to: '+573001234567',
text: 'Hola Ana, tu pedido #1042 sale hoy.',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/sms',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'to': '+573001234567',
'text': 'Hola Ana, tu pedido #1042 sale hoy.',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/sms');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '+573001234567',
'text' => 'Hola Ana, tu pedido #1042 sale hoy.',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"id": "40319a3e-7e2c-4f4e-9b0e-2c1d5f8a9b10",
"from": "+17869572575",
"to": "+573001234567",
"parts": 1,
"energy": 3,
"contact_id": "6ac9f1e6af6d42a269f21b15",
"message_id": "6ac9f2a1af6d42a269f21c02"
}| الحالة | الطاقة لكل جزء |
|---|---|
| رسالة إلى رقم +1 | 1 (يتطلب 10DLC) |
| رسالة إلى أي دولة أخرى | 3 |
| رسالة مستلمة | 1 |
تُرسل الرسالة الطويلة في عدة أجزاء: حتى 160 حرفًا جزء واحد؛ ومع الرموز التعبيرية أو الأحرف خارج أبجدية GSM حتى 70. وما زاد يُحتسب لكل جزء.
يتصل الذكاء الاصطناعي لوكيلك بالرقم بالهدف الذي تحدده في reason (حتى 2000 حرف). الحقول: to (E.164)، وreason، وcontact_id (اختياري: جهة الاتصال في TBit؛ وبدونه يُبحث عنها بالرقم وتُنشأ إن لم توجد). الاستجابة 202: تم طلب المكالمة. تكلف 6 من الطاقة لكل دقيقة وتُحتسب عند انتهائها؛ حاليًا يمكن الاتصال بأرقام كولومبيا فقط.
وضع الإشعار: إذا أرسلت message (حتى 1.000 حرف) بدلًا من reason، فإن المكالمة تُبلغ فقط. تقول الـ AI ذلك النص كما هو بعد ثوانٍ من الرد (دون انتظار تحدث الشخص)، وتودع وتغلق؛ لا تتحاور ولا تجيب على الأسئلة. مع message، يكون reason اختياريًا ويُستخدم كسياق. تجري المكالمة عبر خط وكيلك وتُحتسب بنفس الطريقة: 6 من الطاقة لكل دقيقة بدأت.
/v1/callscurl -X POST "https://rest-api.tbit.app/v1/calls" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+573001234567",
"reason": "Confirmar la cita de mañana a las 10:00 y ofrecer cambiarla si no puede."
}'const response = await fetch('https://rest-api.tbit.app/v1/calls', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '+573001234567',
reason: 'Confirmar la cita de mañana a las 10:00 y ofrecer cambiarla si no puede.',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/calls',
{
to: '+573001234567',
reason: 'Confirmar la cita de mañana a las 10:00 y ofrecer cambiarla si no puede.',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/calls',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'to': '+573001234567',
'reason': 'Confirmar la cita de mañana a las 10:00 y ofrecer cambiarla si no puede.',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/calls');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '+573001234567',
'reason' => 'Confirmar la cita de mañana a las 10:00 y ofrecer cambiarla si no puede.',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"call_id": "6ac9f3b7af6d42a269f21c10",
"provider_call_id": "conv_8f2k1x",
"from": "+576019190351",
"to": "+573001234567",
"contact_id": "6ac9f1e6af6d42a269f21b15",
"status": "requested"
}/v1/callscurl -X POST "https://rest-api.tbit.app/v1/calls" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+573001234567",
"message": "Tu pago de 250 USD fue aprobado. Ya puedes verlo en tu cuenta."
}'const response = await fetch('https://rest-api.tbit.app/v1/calls', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '+573001234567',
message: 'Tu pago de 250 USD fue aprobado. Ya puedes verlo en tu cuenta.',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/calls',
{
to: '+573001234567',
message: 'Tu pago de 250 USD fue aprobado. Ya puedes verlo en tu cuenta.',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/calls',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'to': '+573001234567',
'message': 'Tu pago de 250 USD fue aprobado. Ya puedes verlo en tu cuenta.',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/calls');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '+573001234567',
'message' => 'Tu pago de 250 USD fue aprobado. Ya puedes verlo en tu cuenta.',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);تظهر الرسائل النصية التي تُكتب إلى خطك في صندوق وارد TBit كمحادثة عبر SMS. لا تجيب عليها الـ AI. كل واحدة تستهلك 1 من الطاقة لكل جزء.
بالإضافة إلى الحد العام البالغ 100 طلب في الدقيقة، يقبل كل من هذه الـ endpoints حتى 30 في الدقيقة لكل وكيل.
| الحالة | الرمز | الوصف |
|---|---|---|
409 | NO_PHONE_LINE | الوكيل ليس لديه خط هاتفي نشط |
422 | DESTINATION_NOT_ALLOWED | الوجهة غير مفعّلة بعد (أرقام +1 تتطلب 10DLC) |
402 | INSUFFICIENT_ENERGY | الطاقة غير كافية؛ لم يُرسل ولم يُتصل |
502 | PROVIDER_ERROR | رفض المشغل الإرسال أو المكالمة؛ يحمل message سببه |