API
संपर्क
संपर्कों की जानकारी देखें और अपडेट करें
# संपर्क > संपर्कों की जानकारी देखें और अपडेट करें - पेज: https://tbit.app/hi/docs/api/contacts - Base URL: `https://rest-api.tbit.app/v1` - ऑथेंटिकेशन: हर request में आपकी key के साथ `X-API-Key` header (उदाहरण इसे `TBIT_API_KEY` environment variable से पढ़ते हैं) ## सामान्य जानकारी संपर्क उन लोगों को दर्शाते हैं जो WhatsApp, Instagram और email जैसे चैनलों के ज़रिए आपके एजेंट से बातचीत करते हैं। हर संपर्क की एक प्रोफ़ाइल होती है जिसमें नाम, चैनल पहचानकर्ता और वैकल्पिक मेटाडेटा होते हैं। ## एंडपॉइंट | तरीका | रूट | विवरण | | --- | --- | --- | | `GET` | `/v1/contacts` | संपर्कों की सूची बनाएं | | `GET` | `/v1/contacts/:id` | किसी संपर्क का विवरण देखें | | `POST` | `/v1/contacts` | संपर्क बनाएं | | `PATCH` | `/v1/contacts/:id` | संपर्क अपडेट करें | | `PUT` | `/v1/contacts` | फ़ोन या ईमेल से बनाएं या अपडेट करें (upsert) | | `GET` | `/v1/contacts?phone=\|email=` | फ़ोन या ईमेल से संपर्क खोजें | | `PATCH` | `/v1/contacts/:id/attributes` | संपर्क के attributes सेव करें | | `PUT` | `/v1/contacts/:id/stage` | संपर्क को किसी फ़नल के चरण में डालें | | `POST` | `/v1/contacts/:id/events` | उसकी timeline में एक इवेंट जोड़ें | ## क्वेरी पैरामीटर लिस्टिंग एंडपॉइंट इन क्वेरी पैरामीटर का समर्थन करता है: | पैरामीटर | प्रकार | विवरण | | --- | --- | --- | | `limit` | `number` | प्रति पेज परिणाम (डिफ़ॉल्ट: 20, अधिकतम: 100) | | `offset` | `number` | छोड़े जाने वाले परिणामों की संख्या (डिफ़ॉल्ट: 0) | ## संपर्कों की सूची बनाएं `GET /v1/contacts` ```bash curl "https://rest-api.tbit.app/v1/contacts?limit=20&offset=0" \ -H "X-API-Key: $TBIT_API_KEY" ``` ## संपर्क का विवरण प्राप्त करें `GET /v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1` ```bash curl "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1" \ -H "X-API-Key: $TBIT_API_KEY" ``` ## संपर्क अपडेट करें `PATCH /v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1` ```bash curl -X PATCH "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "profile_name": "Jane Doe", "email": "[email protected]", "notes": "Preferred language: English" }' ``` ## संपर्क बनाएं custom_attributes को कुछ भी लिखने से पहले «Guardar atributos» के समान नियमों से मान्य किया जाता है। अगर कोई मान मान्य नहीं है तो 400 VALIDATION_ERROR के साथ हर key का कारण (Invalid custom_attributes: «clave»: «motivo») लौटाता है और न संपर्क सेव होता है न उसके attributes। जो attribute मौजूद नहीं है वह मान से अनुमानित प्रकार के साथ बनाया जाता है। `POST /v1/contacts` ```bash curl -X POST "https://rest-api.tbit.app/v1/contacts" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "channel_id": "573009876543", "channel_type": "whatsapp", "profile_name": "Jane Doe", "custom_attributes": { "city": "Bogota", "plan": "premium" } }' ``` ## फ़ोन या ईमेल से बनाएं या अपडेट करें आपके एजेंट के संपर्क को उसके WhatsApp (E.164, «+» के साथ या बिना) से खोजता है और, अगर नहीं मिलता, तो उसके ईमेल से। अगर मौजूद नहीं है तो बनाता है; अगर मौजूद है तो उसमें जो चैनल नहीं है वह जोड़ता है। संपर्क का पहले से मौजूद नाम कभी नहीं बदलता। बनाने पर 201 और मिलने पर 200 लौटाता है। अगर फ़ोन और ईमेल दो अलग संपर्कों के हैं तो 409 CONTACT_CONFLICT के साथ दोनों ids लौटाता है और कुछ नहीं लिखता। आपके भेजे attributes संपर्क को छूने से पहले मान्य किए जाते हैं (देखें «Guardar atributos»)। `PUT /v1/contacts` ```bash curl -X PUT "https://rest-api.tbit.app/v1/contacts" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "phone": "+573001234567", "email": "[email protected]", "first_name": "Ana", "last_name": "Pérez", "attributes": { "plan": "premium" } }' ``` Response: ```json { "data": { "created": true, "matched_by": null, "contact": { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "first_name": "Ana", "last_name": "Pérez", "profile_name": "Ana Pérez", "phone": "573001234567", "email": "[email protected]", "channels": [ { "channel_type": "whatsapp", "channel_id": "573001234567" }, { "channel_type": "email", "channel_id": "[email protected]" } ], "attributes": { "plan": "premium", "ciudad": "Bogotá" }, "stages": [ { "funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa", "funnel_name": "Clientes", "stage": "prueba", "stage_name": "En prueba" } ], "created_at": "2026-10-01T12:00:00.000Z", "updated_at": "2026-10-08T15:00:00.000Z" } } } ``` ## फ़ोन या ईमेल से खोजें आपके एजेंट के उन अधिकतम 10 संपर्कों को लौटाता है जिनके पास वह WhatsApp (किसी भी रूप में) या वह ईमेल है, उनके attributes और जिन फ़नल चरणों में वे हैं उनके साथ। phone या email के बिना, एंडपॉइंट अभी भी हमेशा वाली पेजिनेटेड लिस्टिंग ही रहता है। `GET /v1/contacts` ```bash curl "https://rest-api.tbit.app/v1/contacts?email=ana%40example.com" \ -H "X-API-Key: $TBIT_API_KEY" ``` Response: ```json { "data": [ { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "first_name": "Ana", "last_name": "Pérez", "profile_name": "Ana Pérez", "phone": "573001234567", "email": "[email protected]", "channels": [ { "channel_type": "whatsapp", "channel_id": "573001234567" }, { "channel_type": "email", "channel_id": "[email protected]" } ], "attributes": { "plan": "premium", "ciudad": "Bogotá" }, "stages": [ { "funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa", "funnel_name": "Clientes", "stage": "prueba", "stage_name": "En prueba" } ], "created_at": "2026-10-01T12:00:00.000Z", "updated_at": "2026-10-08T15:00:00.000Z" } ] } ``` ## attributes सेव करें कुंजियाँ attribute का नाम हैं, जैसा «Datos del contacto» में दिखता है (बड़े अक्षरों या तिलकों से फ़र्क नहीं पड़ता)। सब या कुछ नहीं: अगर कोई key मौजूद नहीं है तो 422 UNKNOWN_ATTRIBUTES के साथ details.missing में सूची लौटाता है, और अगर कोई मान अपने प्रकार में नहीं बैठता (सूची में न होने वाला विकल्प, संख्या न होने वाली संख्या, पढ़ी न जा सकने वाली तारीख) तो 422 INVALID_VALUE लौटाता है; दोनों मामलों में कुछ भी सेव नहीं होता। तारीख़ें: चार रूप स्वीकार किए जाते हैं: पूरी तारीख़ (2026-11-14), साल और महीना (2026-11), बिना साल के दिन और महीना (--11-14) या सिर्फ़ महीना (--11)। समय वाली तारीख़ (2026-11-14T15:00:00Z) उसके दिन के रूप में सेव होती है, और API इसे हमेशा बिना समय के लौटाती है (2026-11-14)। ऑब्जेक्ट की सूचियाँ, जैसे “ख़ास तारीख़ें”: हर आइटम अपने schema के ख़िलाफ़ validate होता है। तारीख़ के फ़ील्ड इन चार रूपों का इस्तेमाल करते हैं, ज़रूरी फ़ील्ड ख़ाली नहीं हो सकते और विकल्पों वाले फ़ील्ड सूची में से एक होने चाहिए (बड़े अक्षरों और मात्राओं से फ़र्क़ नहीं पड़ता; विकल्प जैसा लिखा है वैसा ही सेव होता है)। create_missing: true के साथ जो नहीं हैं वे बन जाते हैं (टाइप value से तय होता है)। null value को मिटा देता है। हर नई value “भरा हुआ attribute” गिनी जाती है: उस attribute पर नियम वाला funnel कार्ड को वैसे ही आगे बढ़ाता है जैसे AI के भरने पर। `PATCH /v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes` ```bash curl -X PATCH "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "attributes": { "plan": "premium", "ciudad": "Bogotá" }, "create_missing": false }' ``` Response: ```json { "data": { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "attributes": { "plan": "premium", "ciudad": "Bogotá" }, "updated": [ "plan", "ciudad" ], "created_attributes": [] } } ``` ## funnel के एक stage में डालें funnel को funnel_id से या उसके नाम (funnel) से बताएँ और stage को उसके slug से। अगर contact उस funnel में नहीं है तो उसे जोड़ देता है; अगर किसी और stage में है तो उसे आगे बढ़ा देता है; अगर पहले से वहीं है तो कुछ नहीं करता (changed: false)। stage की entry actions चलती हैं और यह contact के history में रहता है। डिफ़ॉल्ट रूप से टीम की घंटी नहीं बजती: अगर आपको सूचना चाहिए तो notify: true भेजें। एरर: 404 FUNNEL_NOT_FOUND और 422 UNKNOWN_STAGE (stage की सूची के साथ)। `PUT /v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage` ```bash curl -X PUT "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "funnel": "Clientes", "stage": "prueba" }' ``` Response: ```json { "data": { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa", "stage": "prueba", "previous_stage": "registrado", "changed": true } } ``` ## timeline में एक event जोड़ें contact की फ़ाइल में एक milestone छोड़ता है, उसकी तारीख़ के साथ (occurred_at, डिफ़ॉल्ट रूप से अभी; भविष्य की नहीं हो सकती)। idempotency_key के साथ वही event दोहराया नहीं जाता: वही call दोबारा करने पर 200 के साथ duplicate: true और मूल event मिलता है। data में text, number या boolean वाली 20 तक keys स्वीकार होती हैं। किसी और agent के contacts 404 लौटाते हैं, वैसे ही जैसे कोई मौजूद न हो। `POST /v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events` ```bash curl -X POST "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Empezó la prueba gratis", "description": "Termina el 15 de octubre", "occurred_at": "2026-10-08T15:00:00Z", "idempotency_key": "trial:64f1a2b3c4d5e6f7a8b9c0d1:2026-10-08", "data": { "plan": "monthly" } }' ``` Response: ```json { "data": { "id": "6ac85d7e32e0335e1dcac4fd", "contact_id": "64f1a2b3c4d5e6f7a8b9c0d1", "name": "Empezó la prueba gratis", "occurred_at": "2026-10-08T15:00:00.000Z", "duplicate": false } } ``` ## रिस्पॉन्स फ़ॉर्मैट लिस्टिंग endpoints पेज किए गए नतीजे लौटाते हैं: ```json { "data": [ { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "profile_name": "Jane Doe", "email": "[email protected]", "notes": "Preferred language: English", "channels": [ { "channel_id": "573001234567", "channel_type": "whatsapp" } ], "custom_attributes": { "city": "Bogota", "plan": "premium" }, "created_at": "2024-09-01T12:00:00Z", "updated_at": "2024-09-01T14:30:00Z" } ], "pagination": { "total": 50, "limit": 20, "offset": 0, "has_more": true } } ```संपर्क उन लोगों को दर्शाते हैं जो WhatsApp, Instagram और email जैसे चैनलों के ज़रिए आपके एजेंट से बातचीत करते हैं। हर संपर्क की एक प्रोफ़ाइल होती है जिसमें नाम, चैनल पहचानकर्ता और वैकल्पिक मेटाडेटा होते हैं।
| तरीका | रूट | विवरण |
|---|---|---|
| GET | /v1/contacts | संपर्कों की सूची बनाएं |
| GET | /v1/contacts/:id | किसी संपर्क का विवरण देखें |
| POST | /v1/contacts | संपर्क बनाएं |
| PATCH | /v1/contacts/:id | संपर्क अपडेट करें |
| PUT | /v1/contacts | फ़ोन या ईमेल से बनाएं या अपडेट करें (upsert) |
| GET | /v1/contacts?phone=|email= | फ़ोन या ईमेल से संपर्क खोजें |
| PATCH | /v1/contacts/:id/attributes | संपर्क के attributes सेव करें |
| PUT | /v1/contacts/:id/stage | संपर्क को किसी फ़नल के चरण में डालें |
| POST | /v1/contacts/:id/events | उसकी timeline में एक इवेंट जोड़ें |
लिस्टिंग एंडपॉइंट इन क्वेरी पैरामीटर का समर्थन करता है:
| पैरामीटर | प्रकार | विवरण |
|---|---|---|
limit | number | प्रति पेज परिणाम (डिफ़ॉल्ट: 20, अधिकतम: 100) |
offset | number | छोड़े जाने वाले परिणामों की संख्या (डिफ़ॉल्ट: 0) |
/v1/contactscurl "https://rest-api.tbit.app/v1/contacts?limit=20&offset=0" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/contacts?limit=20&offset=0', {
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.get(
'https://rest-api.tbit.app/v1/contacts?limit=20&offset=0',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/contacts?limit=20&offset=0',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts?limit=20&offset=0');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1curl "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1', {
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.get(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1curl -X PATCH "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"profile_name": "Jane Doe",
"email": "[email protected]",
"notes": "Preferred language: English"
}'const response = await fetch('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1', {
method: 'PATCH',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
profile_name: 'Jane Doe',
email: '[email protected]',
notes: 'Preferred language: English',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.patch(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1',
{
profile_name: 'Jane Doe',
email: '[email protected]',
notes: 'Preferred language: English',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.patch(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'profile_name': 'Jane Doe',
'email': '[email protected]',
'notes': 'Preferred language: English',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'profile_name' => 'Jane Doe',
'email' => '[email protected]',
'notes' => 'Preferred language: English',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);custom_attributes को कुछ भी लिखने से पहले «Guardar atributos» के समान नियमों से मान्य किया जाता है। अगर कोई मान मान्य नहीं है तो 400 VALIDATION_ERROR के साथ हर key का कारण (Invalid custom_attributes: «clave»: «motivo») लौटाता है और न संपर्क सेव होता है न उसके attributes। जो attribute मौजूद नहीं है वह मान से अनुमानित प्रकार के साथ बनाया जाता है।
/v1/contactscurl -X POST "https://rest-api.tbit.app/v1/contacts" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "573009876543",
"channel_type": "whatsapp",
"profile_name": "Jane Doe",
"custom_attributes": {
"city": "Bogota",
"plan": "premium"
}
}'const response = await fetch('https://rest-api.tbit.app/v1/contacts', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
channel_id: '573009876543',
channel_type: 'whatsapp',
profile_name: 'Jane Doe',
custom_attributes: {
city: 'Bogota',
plan: 'premium',
},
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/contacts',
{
channel_id: '573009876543',
channel_type: 'whatsapp',
profile_name: 'Jane Doe',
custom_attributes: {
city: 'Bogota',
plan: 'premium',
},
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/contacts',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'channel_id': '573009876543',
'channel_type': 'whatsapp',
'profile_name': 'Jane Doe',
'custom_attributes': {
'city': 'Bogota',
'plan': 'premium',
},
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts');
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([
'channel_id' => '573009876543',
'channel_type' => 'whatsapp',
'profile_name' => 'Jane Doe',
'custom_attributes' => [
'city' => 'Bogota',
'plan' => 'premium',
],
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);आपके एजेंट के संपर्क को उसके WhatsApp (E.164, «+» के साथ या बिना) से खोजता है और, अगर नहीं मिलता, तो उसके ईमेल से। अगर मौजूद नहीं है तो बनाता है; अगर मौजूद है तो उसमें जो चैनल नहीं है वह जोड़ता है। संपर्क का पहले से मौजूद नाम कभी नहीं बदलता। बनाने पर 201 और मिलने पर 200 लौटाता है।
अगर फ़ोन और ईमेल दो अलग संपर्कों के हैं तो 409 CONTACT_CONFLICT के साथ दोनों ids लौटाता है और कुछ नहीं लिखता। आपके भेजे attributes संपर्क को छूने से पहले मान्य किए जाते हैं (देखें «Guardar atributos»)।
/v1/contactscurl -X PUT "https://rest-api.tbit.app/v1/contacts" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+573001234567",
"email": "[email protected]",
"first_name": "Ana",
"last_name": "Pérez",
"attributes": {
"plan": "premium"
}
}'const response = await fetch('https://rest-api.tbit.app/v1/contacts', {
method: 'PUT',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
phone: '+573001234567',
email: '[email protected]',
first_name: 'Ana',
last_name: 'Pérez',
attributes: {
plan: 'premium',
},
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.put(
'https://rest-api.tbit.app/v1/contacts',
{
phone: '+573001234567',
email: '[email protected]',
first_name: 'Ana',
last_name: 'Pérez',
attributes: {
plan: 'premium',
},
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.put(
'https://rest-api.tbit.app/v1/contacts',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'phone': '+573001234567',
'email': '[email protected]',
'first_name': 'Ana',
'last_name': 'Pérez',
'attributes': {
'plan': 'premium',
},
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'phone' => '+573001234567',
'email' => '[email protected]',
'first_name' => 'Ana',
'last_name' => 'Pérez',
'attributes' => [
'plan' => 'premium',
],
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"created": true,
"matched_by": null,
"contact": {
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"first_name": "Ana",
"last_name": "Pérez",
"profile_name": "Ana Pérez",
"phone": "573001234567",
"email": "[email protected]",
"channels": [
{
"channel_type": "whatsapp",
"channel_id": "573001234567"
},
{
"channel_type": "email",
"channel_id": "[email protected]"
}
],
"attributes": {
"plan": "premium",
"ciudad": "Bogotá"
},
"stages": [
{
"funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa",
"funnel_name": "Clientes",
"stage": "prueba",
"stage_name": "En prueba"
}
],
"created_at": "2026-10-01T12:00:00.000Z",
"updated_at": "2026-10-08T15:00:00.000Z"
}
}
}आपके एजेंट के उन अधिकतम 10 संपर्कों को लौटाता है जिनके पास वह WhatsApp (किसी भी रूप में) या वह ईमेल है, उनके attributes और जिन फ़नल चरणों में वे हैं उनके साथ। phone या email के बिना, एंडपॉइंट अभी भी हमेशा वाली पेजिनेटेड लिस्टिंग ही रहता है।
/v1/contactscurl "https://rest-api.tbit.app/v1/contacts?email=ana%40example.com" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/contacts?email=ana%40example.com', {
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.get(
'https://rest-api.tbit.app/v1/contacts?email=ana%40example.com',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/contacts?email=ana%40example.com',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts?email=ana%40example.com');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": [
{
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"first_name": "Ana",
"last_name": "Pérez",
"profile_name": "Ana Pérez",
"phone": "573001234567",
"email": "[email protected]",
"channels": [
{
"channel_type": "whatsapp",
"channel_id": "573001234567"
},
{
"channel_type": "email",
"channel_id": "[email protected]"
}
],
"attributes": {
"plan": "premium",
"ciudad": "Bogotá"
},
"stages": [
{
"funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa",
"funnel_name": "Clientes",
"stage": "prueba",
"stage_name": "En prueba"
}
],
"created_at": "2026-10-01T12:00:00.000Z",
"updated_at": "2026-10-08T15:00:00.000Z"
}
]
}कुंजियाँ attribute का नाम हैं, जैसा «Datos del contacto» में दिखता है (बड़े अक्षरों या तिलकों से फ़र्क नहीं पड़ता)। सब या कुछ नहीं: अगर कोई key मौजूद नहीं है तो 422 UNKNOWN_ATTRIBUTES के साथ details.missing में सूची लौटाता है, और अगर कोई मान अपने प्रकार में नहीं बैठता (सूची में न होने वाला विकल्प, संख्या न होने वाली संख्या, पढ़ी न जा सकने वाली तारीख) तो 422 INVALID_VALUE लौटाता है; दोनों मामलों में कुछ भी सेव नहीं होता।
तारीख़ें: चार रूप स्वीकार किए जाते हैं: पूरी तारीख़ (2026-11-14), साल और महीना (2026-11), बिना साल के दिन और महीना (--11-14) या सिर्फ़ महीना (--11)। समय वाली तारीख़ (2026-11-14T15:00:00Z) उसके दिन के रूप में सेव होती है, और API इसे हमेशा बिना समय के लौटाती है (2026-11-14)। ऑब्जेक्ट की सूचियाँ, जैसे “ख़ास तारीख़ें”: हर आइटम अपने schema के ख़िलाफ़ validate होता है। तारीख़ के फ़ील्ड इन चार रूपों का इस्तेमाल करते हैं, ज़रूरी फ़ील्ड ख़ाली नहीं हो सकते और विकल्पों वाले फ़ील्ड सूची में से एक होने चाहिए (बड़े अक्षरों और मात्राओं से फ़र्क़ नहीं पड़ता; विकल्प जैसा लिखा है वैसा ही सेव होता है)।
create_missing: true के साथ जो नहीं हैं वे बन जाते हैं (टाइप value से तय होता है)। null value को मिटा देता है। हर नई value “भरा हुआ attribute” गिनी जाती है: उस attribute पर नियम वाला funnel कार्ड को वैसे ही आगे बढ़ाता है जैसे AI के भरने पर।
/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributescurl -X PATCH "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"attributes": {
"plan": "premium",
"ciudad": "Bogotá"
},
"create_missing": false
}'const response = await fetch('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes', {
method: 'PATCH',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
attributes: {
plan: 'premium',
ciudad: 'Bogotá',
},
create_missing: false,
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.patch(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes',
{
attributes: {
plan: 'premium',
ciudad: 'Bogotá',
},
create_missing: false,
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.patch(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'attributes': {
'plan': 'premium',
'ciudad': 'Bogotá',
},
'create_missing': False,
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'attributes' => [
'plan' => 'premium',
'ciudad' => 'Bogotá',
],
'create_missing' => false,
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"attributes": {
"plan": "premium",
"ciudad": "Bogotá"
},
"updated": [
"plan",
"ciudad"
],
"created_attributes": []
}
}funnel को funnel_id से या उसके नाम (funnel) से बताएँ और stage को उसके slug से। अगर contact उस funnel में नहीं है तो उसे जोड़ देता है; अगर किसी और stage में है तो उसे आगे बढ़ा देता है; अगर पहले से वहीं है तो कुछ नहीं करता (changed: false)। stage की entry actions चलती हैं और यह contact के history में रहता है।
डिफ़ॉल्ट रूप से टीम की घंटी नहीं बजती: अगर आपको सूचना चाहिए तो notify: true भेजें। एरर: 404 FUNNEL_NOT_FOUND और 422 UNKNOWN_STAGE (stage की सूची के साथ)।
/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stagecurl -X PUT "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"funnel": "Clientes",
"stage": "prueba"
}'const response = await fetch('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage', {
method: 'PUT',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
funnel: 'Clientes',
stage: 'prueba',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.put(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage',
{
funnel: 'Clientes',
stage: 'prueba',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.put(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'funnel': 'Clientes',
'stage': 'prueba',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'funnel' => 'Clientes',
'stage' => 'prueba',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa",
"stage": "prueba",
"previous_stage": "registrado",
"changed": true
}
}contact की फ़ाइल में एक milestone छोड़ता है, उसकी तारीख़ के साथ (occurred_at, डिफ़ॉल्ट रूप से अभी; भविष्य की नहीं हो सकती)। idempotency_key के साथ वही event दोहराया नहीं जाता: वही call दोबारा करने पर 200 के साथ duplicate: true और मूल event मिलता है। data में text, number या boolean वाली 20 तक keys स्वीकार होती हैं।
किसी और agent के contacts 404 लौटाते हैं, वैसे ही जैसे कोई मौजूद न हो।
/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/eventscurl -X POST "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Empezó la prueba gratis",
"description": "Termina el 15 de octubre",
"occurred_at": "2026-10-08T15:00:00Z",
"idempotency_key": "trial:64f1a2b3c4d5e6f7a8b9c0d1:2026-10-08",
"data": {
"plan": "monthly"
}
}'const response = await fetch('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Empezó la prueba gratis',
description: 'Termina el 15 de octubre',
occurred_at: '2026-10-08T15:00:00Z',
idempotency_key: 'trial:64f1a2b3c4d5e6f7a8b9c0d1:2026-10-08',
data: {
plan: 'monthly',
},
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events',
{
name: 'Empezó la prueba gratis',
description: 'Termina el 15 de octubre',
occurred_at: '2026-10-08T15:00:00Z',
idempotency_key: 'trial:64f1a2b3c4d5e6f7a8b9c0d1:2026-10-08',
data: {
plan: 'monthly',
},
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'name': 'Empezó la prueba gratis',
'description': 'Termina el 15 de octubre',
'occurred_at': '2026-10-08T15:00:00Z',
'idempotency_key': 'trial:64f1a2b3c4d5e6f7a8b9c0d1:2026-10-08',
'data': {
'plan': 'monthly',
},
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events');
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([
'name' => 'Empezó la prueba gratis',
'description' => 'Termina el 15 de octubre',
'occurred_at' => '2026-10-08T15:00:00Z',
'idempotency_key' => 'trial:64f1a2b3c4d5e6f7a8b9c0d1:2026-10-08',
'data' => [
'plan' => 'monthly',
],
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"id": "6ac85d7e32e0335e1dcac4fd",
"contact_id": "64f1a2b3c4d5e6f7a8b9c0d1",
"name": "Empezó la prueba gratis",
"occurred_at": "2026-10-08T15:00:00.000Z",
"duplicate": false
}
}लिस्टिंग endpoints पेज किए गए नतीजे लौटाते हैं:
{
"data": [
{
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"profile_name": "Jane Doe",
"email": "[email protected]",
"notes": "Preferred language: English",
"channels": [
{
"channel_id": "573001234567",
"channel_type": "whatsapp"
}
],
"custom_attributes": {
"city": "Bogota",
"plan": "premium"
},
"created_at": "2024-09-01T12:00:00Z",
"updated_at": "2024-09-01T14:30:00Z"
}
],
"pagination": {
"total": 50,
"limit": 20,
"offset": 0,
"has_more": true
}
}