CID Lookup تلفن ابری همکاران

CID Lookup چیست؟

CID Lookup قابلیتی برای شناسایی تماس‌گیرنده یا مخاطب تماس خروجی است. تلفن ابری همکاران شماره را به سامانه شما ارسال می‌کند و سامانه شما نام مخاطب را به‌صورت یک رشته متنی بازمی‌گرداند.

نحوه عملکرد

تلفن ابری عبارت [NUMBER] را در URL تنظیم‌شده با شماره واقعی جایگزین می‌کند. پاسخ سرویس باید فقط شامل نام قابل نمایش باشد.

پیش‌نیازهای سرویس

شروع سریع

یک Endpoint در نرم‌افزار خود ایجاد کنید و آدرس آن را به شکل زیر در اختیار تیم پشتیبانی قرار دهید:

https://crm.example.com/api/cid-lookup?number=[NUMBER]

هنگام تماس شماره جایگزین می‌شود:

GET /api/cid-lookup?number=09121234567 HTTP/1.1
Host: crm.example.com
Accept: text/plain

ساختار درخواست

درخواست به‌صورت GET ارسال می‌شود و شماره در بخشی از URL که با [NUMBER] مشخص شده قرار می‌گیرد.

ساختار پاسخ

در صورت یافتن مخاطب، فقط نام موردنظر را در بدنه پاسخ برگردانید.

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

علی محمدی

مخاطب پیدا نشد

در صورت پیدا نشدن شماره، پاسخ خالی یا یک نام عمومی کوتاه برگردانید. رفتار نهایی باید پیش از فعال‌سازی با تیم فنی هماهنگ شود.

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

قالب شماره‌ها و نرمال‌سازی

شماره ممکن است با قالب‌های متفاوت دریافت شود. Endpoint شما باید همه قالب‌های رایج را به یک قالب داخلی تبدیل کند.

زبان، طول نام و Encoding

• پاسخ را با Encoding استاندارد UTF-8 ارسال کنید.
• نام را کوتاه و قابل نمایش نگه دارید؛ مانند «علی محمدی» یا «شرکت نمونه».
• برخی تلفن‌های سخت‌افزاری قدیمی ممکن است حروف فارسی را درست نمایش ندهند.
• از ارسال HTML، خط جدید، توضیحات اضافی یا داده حساس خودداری کنید.

نمونه PHP / Laravel

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use App\Models\Contact;

Route::get('/api/cid-lookup', function (Request $request) {
    $number = normalizePhone((string) $request->query('number'));

    $contact = Contact::query()
        ->where('normalized_phone', $number)
        ->first();

    return response($contact?->display_name ?? '', 200)
        ->header('Content-Type', 'text/plain; charset=utf-8');
});

نمونه Node.js / Express

import express from "express";

const app = express();

app.get("/api/cid-lookup", async (req, res) => {
  const number = normalizePhone(String(req.query.number || ""));
  const contact = await contacts.findByPhone(number);

  res.type("text/plain; charset=utf-8");
  res.status(200).send(contact?.displayName || "");
});

app.listen(3000);

نمونه Python / Flask

from flask import Flask, request, Response

app = Flask(__name__)

@app.get('/api/cid-lookup')
def cid_lookup():
    number = normalize_phone(request.args.get('number', ''))
    contact = find_contact_by_phone(number)
    name = contact.display_name if contact else ''

    return Response(name, status=200, content_type='text/plain; charset=utf-8')

تست سرویس

پیش از ارسال درخواست فعال‌سازی، Endpoint را با چند شماره واقعی و ناشناس آزمایش کنید.

curl -i "https://crm.example.com/api/cid-lookup?number=09121234567"

امنیت

• فقط اطلاعات لازم برای نمایش نام مخاطب را برگردانید.
• از قرار دادن کلیدهای حساس در URL عمومی خودداری کنید.
• در صورت استفاده از Token، آن را طولانی و قابل تعویض انتخاب کنید.
• Rate Limit منطقی تعریف کنید، اما تماس‌های واقعی را مسدود نکنید.
• ورودی شماره را اعتبارسنجی و از Queryهای پارامتری استفاده کنید.
• اطلاعات شماره‌ها و پاسخ‌ها را بدون ضرورت در Log عمومی ذخیره نکنید.

کارایی و دسترس‌پذیری

CID Lookup در مسیر بلادرنگ تماس اجرا می‌شود. بنابراین پایداری و سرعت Endpoint اهمیت مستقیم دارد.

عیب‌یابی

فعال‌سازی CID Lookup

پس از آماده‌سازی و تست Endpoint، URL نهایی را از طریق تیکت پشتیبانی ارسال کنید.

عنوان درخواست: فعال‌سازی CID Lookup
کد مرکز تماس: [کد مرکز تماس]
URL استعلام: https://crm.example.com/api/cid-lookup?number=[NUMBER]
نوع پاسخ: text/plain; charset=utf-8
شماره تست: [شماره ثبت‌شده در CRM]