API ও ওয়েবহুক দিয়ে আপনার নিজের সফটওয়্যার যুক্ত করুন

শুধু সেই টুলের প্রয়োজনীয় অনুমতিসহ একটি কী তৈরি করুন

সেটিংস → API ও ওয়েবহুক → কী তৈরি করুন। ব্যক্তির নামে নয়, টুলের নামে এর নাম দিন — কয়েক মাস পরে এই তালিকায় ও নিরাপত্তা লগে আপনি এই নামটিই দেখবেন। তারপর অনুমতিগুলিতে টিক দিন, এবং শুধু সেগুলিতেই: যে কী শুধু পড়তে পারে, তাকে দিয়ে কিছুই লেখানো যায় না।

• leads:read — লিড, ধাপ ও ফলাফল পড়া
• leads:write — লিড তৈরি, আপডেট ও মুছে ফেলা, নোট যোগ করা
• calls:read — কলের ইতিহাস পড়া
• users:read — এই ওয়ার্কস্পেসের মানুষদের তথ্য পড়া
• webhooks:manage — ওয়েবহুক তৈরি ও মুছে ফেলা

এখনই কপি করুন — এটি একবারই দেখানো হয়

কী শুরু হয় lk_live_ দিয়ে এবং ঠিক একবারই দেখা যায়, তৈরি করার সঙ্গে সঙ্গে আসা ডায়ালগে। শুধু এর একটি হ্যাশ সংরক্ষিত থাকে, তাই পরে কেউ এটি আবার পড়তে পারে না; তালিকায় প্রথম কয়েকটি অক্ষর দেখানো হয়, যাতে আপনি কীগুলি আলাদা করে চিনতে পারেন। হারিয়ে ফেললে সমাধান হলো সেই কী প্রত্যাহার করে নতুন একটি তৈরি করা। একটি কী কোনো একজন এজেন্টের নয়, ওয়ার্কস্পেসের — যে ইন্টিগ্রেশন আপনার লিডের শুধু একটি অংশ দেখে, সেটি অর্ধেক ডেটা সিঙ্ক করবে আর ভাঙা মনে হবে — এবং এটি যা কিছু লেখে, তা নিরাপত্তা লগে এর নামেই লিপিবদ্ধ হয়।

বেস URL এবং প্রথম কল

সেটিংস → API ও ওয়েবহুক-এ আপনার বেস URL দেখানো থাকে — বর্তমানে https://api.lumakol.com/api/v1 — এবং প্রতিটি রিকোয়েস্টে কী-টি বেয়ারার টোকেন হিসেবে যায়। প্রথমে যে কলটি করবেন, তা হলো GET /ping: এটি কী-টি কোন ওয়ার্কস্পেসের এবং এতে কী কী অনুমতি আছে তা জানায়, ফলে আসল কোড লেখার আগেই প্রমাণ হয়ে যায় যে কী, হেডার ও ঠিকানা সবই ঠিক আছে। প্রতিটি এন্ডপয়েন্ট, ফিল্ড ও এরর কোড API রেফারেন্সে তালিকাভুক্ত: সেটিংস → API ও ওয়েবহুক → API রেফারেন্স (সাইন ইন করা থাকতে হবে)।

• curl https://api.lumakol.com/api/v1/ping -H "Authorization: Bearer lk_live_…"

আপনার লিডগুলি পড়ুন

GET /leads লিডের একটি পেজ ফেরত দেয়, সঙ্গে প্রত্যাশিত ফিল্টারগুলি: stage, owner, source, tag, টেক্সট সার্চের জন্য q, এবং একবারে সর্বোচ্চ 200 পর্যন্ত limit। উত্তরটি একটি অবজেক্ট, খালি তালিকা নয় — লিডগুলি থাকে data-তে, পাশে next_cursor ও has_more।

• curl "https://api.lumakol.com/api/v1/leads?limit=100" -H "Authorization: Bearer lk_live_…"
• GET /leads/find ফোন, ইমেল বা আপনার নিজের সেট করা external_id দিয়ে একটি লিড খুঁজে দেয়
• GET /stages এবং GET /dispositions আপনার নিজের পাইপলাইন ও ফলাফল তালিকার পেছনের id-গুলি দেয়

পেজিং, এবং একটি কপি হালনাগাদ রাখা

একটি পেজের next_cursor পরের রিকোয়েস্টে cursor হিসেবে ফেরত পাঠান এবং has_more false না হওয়া পর্যন্ত পুনরাবৃত্তি করুন; cursor স্থির থাকে, তাই পেজিং চলাকালীন কোনো লিড বদলালেও আপনার কোনো সারি বাদ পড়ে না। চলমান সিঙ্কের জন্য শেষবার কখন চালিয়েছিলেন তা মনে রাখুন এবং পরের বার সেটি updated_since হিসেবে পাঠান — তখন থেকে যা বদলেছে শুধু সেটুকুই পাবেন, এবং একইভাবে পেজ করে পড়বেন। প্রতিটি কী মিনিটে 60টি রিকোয়েস্ট করতে পারে, একটি ওয়ার্কস্পেস তার সব কী মিলিয়ে মিনিটে 120টি এবং দিনে 10,000টি। API কী পেইড প্ল্যানে পাওয়া যায়, বিনামূল্যের ট্রায়ালে নয়। রেসপন্সে RateLimit-Limit, RateLimit-Remaining ও RateLimit-Reset হেডার থাকে, এবং 429-এর সঙ্গে আসে Retry-After; Remaining শূন্যে পৌঁছালে লুপে বারবার চেষ্টা না করে রিসেটের জন্য অপেক্ষা করুন।

একটি ওয়েবহুক যোগ করুন

সেটিংস → API ও ওয়েবহুক → ওয়েবহুক যোগ করুন। URL অবশ্যই https হতে হবে এবং ইন্টারনেট থেকে পৌঁছানো যেতে হবে — প্রাইভেট বা অভ্যন্তরীণ ঠিকানা সংরক্ষণের সময়ই প্রত্যাখ্যাত হয় এবং প্রতিটি ডেলিভারির আগে আবার যাচাই করা হয়, তাই পরে DNS অন্য দিকে ঘুরিয়েও তা এড়ানো যায় না। যে ইভেন্টগুলি চান সেগুলিতে টিক দিন, তারপর টেস্ট ব্যবহার করে একটি নমুনা ডেলিভারি কিউতে পাঠান এবং ভরসা করার আগে প্রমাণ করে নিন যে আপনার রিসিভার কাজ করছে। ডেলিভারিগুলি পাঠানো হয় একটি কিউ থেকে, যা প্রতি দশ সেকেন্ডে দেখা হয়, তাই তাৎক্ষণিক নয়, কয়েক সেকেন্ডের মধ্যে পৌঁছানোর আশা করুন।

• lead.created — হাতে, API-র মাধ্যমে, ফর্ম, লিড সোর্স, ওয়েবসাইট চ্যাট বা মিসড কল থেকে একটি লিড যোগ হয় (ফাইল ইমপোর্টে নয়)
• lead.updated — অ্যাপে, API-র মাধ্যমে বা কোনো অটোমেশন নিয়মে একটি লিড সম্পাদিত হয় (কলের ফলাফল লগ করলে এর বদলে call.logged পাঠানো হয়)
• lead.stage_changed — একটি লিড পাইপলাইনের অন্য ধাপে যায়
• lead.assigned — একটি লিড কাউকে দেওয়া হয়, বা কারও কাছ থেকে সরিয়ে নেওয়া হয়
• call.logged — একটি কলের বিপরীতে ফলাফল লগ করা হয়
• follow_up.due — মালিক আছে এমন একটি লিডের ফলো-আপ 15 মিনিটের মধ্যে নির্ধারিত

স্বাক্ষর যাচাই করুন

প্রতিটি রিকোয়েস্টে চারটি হেডার থাকে: X-LumaKol-Event, X-LumaKol-Delivery, X-LumaKol-Timestamp এবং X-LumaKol-Signature। স্বাক্ষরটি হলো sha256= এবং তার পরে টাইমস্ট্যাম্প, একটি ফুল স্টপ ও কাঁচা বডির একটি HMAC-SHA256, যার কী হলো ওয়েবহুক তৈরির সময় দেখানো সাইনিং সিক্রেট — এটি শুরু হয় whsec_ দিয়ে। আপনার পুনরায় সিরিয়ালাইজ করা JSON নয়, বরং আসলে যে বাইটগুলি পেয়েছেন তার ওপর এটি আবার গণনা করুন, দুটিকে কনস্ট্যান্ট-টাইম তুলনায় মিলিয়ে দেখুন, এবং যার টাইমস্ট্যাম্প সাম্প্রতিক নয় তা প্রত্যাখ্যান করুন। যে রিকোয়েস্ট মেলে না, সেটি আমাদের কাছ থেকে আসেনি।

• যে স্ট্রিংটি স্বাক্ষরিত হয়, তা হলো টাইমস্ট্যাম্প, একটি ফুল স্টপ, তারপর বডি — ঠিক এই ক্রমে
• X-LumaKol-Delivery প্রতিটি পুনঃপ্রচেষ্টায় একই থাকে: এটি সংরক্ষণ করুন এবং পুনরাবৃত্তি উপেক্ষা করুন, কারণ আমাদের দিকে টাইম আউট হওয়া ডেলিভারি আবার পাঠানো হয়, এমনকি আপনার সার্ভার কাজটি শেষ করে থাকলেও
• “নতুন সিক্রেট” কী বদলে দেয় এবং পুরোনোটি সঙ্গে সঙ্গে কাজ করা বন্ধ করে, তাই আগে আপনার রিসিভার আপডেট করুন

ডেলিভারি লগ ও পুনঃপ্রচেষ্টা

একটি ওয়েবহুকের নিচে “সাম্প্রতিক ডেলিভারি” খুললে শেষ ডেলিভারিগুলি দেখা যায় — ইভেন্ট, সেটি পৌঁছেছে কি না, আপনার সার্ভার কোন স্ট্যাটাস কোড ফেরত দিয়েছে বা আমরা কোন এররে পড়েছি, এবং কখন। 2xx ছাড়া অন্য যেকোনো কিছু — রিডাইরেক্টও ব্যর্থতা হিসেবে গণ্য — পাঁচ মিনিট, পনেরো মিনিট, এক ঘণ্টা, তিন ঘণ্টা, ছয় ঘণ্টা এবং আবার ছয় ঘণ্টা পরে পুনরায় পাঠানো হয়: প্রায় ষোলো ঘণ্টায় সাতটি প্রচেষ্টা, তাই কিছুক্ষণ বন্ধ থাকা রিসিভার কিছুই হারায় না, আর সারাদিন বন্ধ থাকা রিসিভারের ক্ষেত্রে শেষ পর্যন্ত চেষ্টা থামিয়ে দেওয়া হয়। শুধু স্ট্যাটাস কোড বা এরর রাখা হয়, আপনার রেসপন্স বডি নয়। সফল না হওয়া পর্যন্ত, বা আপনি বন্ধ করে আবার চালু না করা পর্যন্ত, ওয়েবহুকটি তার শেষ ব্যর্থতা দেখাতে থাকে।

• সুইচটি ওয়েবহুক না মুছেই সেটিকে থামিয়ে রাখে — রিডিপ্লয়ের সময় ঠিক এটাই দরকার
• ডেলিভারির সারিগুলি ডিবাগিংয়ের সহায়ক, রেকর্ড নয় — প্রায় দুই সপ্তাহ পরে এগুলি মুছে ফেলা হয়
• একটি ওয়েবহুক মুছলে তার জন্য কিউতে থাকা সবকিছু বাদ পড়ে যায়

কাজ ফুরোলে কী প্রত্যাহার করুন

প্রত্যাহার করলে ওই কী ব্যবহারকারী সবকিছু তৎক্ষণাৎ বন্ধ হয়ে যায়, এবং তা আর ফেরানো যায় না — ইচ্ছাকৃতভাবেই কোনো বিরতির বিকল্প নেই। কোনো টুল অবসরে গেলে, যিনি সেটি সেট আপ করেছিলেন তিনি চলে গেলে, অথবা কোনো কী ফাঁস হয়েছে বলে সন্দেহ হওয়ামাত্র প্রত্যাহার করুন, তারপর নতুন একটি তৈরি করে টুলে পেস্ট করুন। তালিকায় দেখা যায় প্রতিটি কী শেষবার কখন ব্যবহৃত হয়েছে — যে কী আর কোনো কিছুর দরকার নেই, সেটি চেনার সবচেয়ে দ্রুত উপায় এটাই।