API Titik Masuk (Entry Points) #

Titik Masuk adalah aturan perutean: “saat ini terjadi di saluran ini, serahkan percakapan ke Agen ini”. Menghubungkan saluran akan memasukkan pesan ke akun dan membuat Agen akan memberi Anda sesuatu yang dapat membalas, tetapi keduanya tidak memutuskan siapa yang menjawab pesan pertama orang asing. Titik Masuklah yang melakukannya. Untuk produk itu sendiri, lihat panduan Titik Masuk.

• URL Dasar — https://api.youraiconnector.com/v1
• Autentikasi — kunci API Anda (lihat Autentikasi)
• Kesalahan & penomoran halaman — lihat Kesalahan & Penomoran Halaman

Semua contoh di bawah ini menunjukkan formulir kueri ?apiKey= dalam cURL dan header X-API-Key dalam JavaScript dan Python — keduanya berfungsi di setiap endpoint.

Di penjelajah API. Setiap endpoint di halaman ini ada dalam spesifikasi OpenAPI yang dipublikasikan, sehingga Anda dapat menelusuri kolom-kolomnya secara tepat dan menjalankan permintaan langsung di penjelajah API.

Satu panggilan yang dibutuhkan sebagian besar integrasi #

Hubungkan saluran, buat Agen, lalu arahkan saluran ke Agen tersebut:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "agent_id": "ag7HkQ2ZpLxR3mNb" }'

Itu adalah keseluruhan pengaturan untuk “Agen ini menjawab WhatsApp”. Segala sesuatu yang lain di halaman ini adalah untuk aturan yang lebih spesifik (kata kunci, komentar, pengikut baru), beberapa nomor pada satu saluran, dan membaca kembali apa yang dikonfigurasi.

Bagaimana perutean diputuskan #

Saat pesan tiba, platform menjalankan tangga tetap dan langkah pertama yang memutuskan akan menang:

1. Seorang manusia telah mengambil alih percakapan — bukan AI.
2. Kontak sudah ditetapkan ke Agen, secara manual atau karena percakapan dengan Agen tersebut sedang berlangsung — Agen yang sama tetap menanganinya. Titik Masuk tidak pernah memindahkan percakapan yang sudah ada; untuk menyerahkan obrolan ke Agen yang berbeda, tetapkan (di aplikasi, atau dengan tindakan Otomatisasi).
3. Kontak membalas siaran — Agen siaran tersebut yang menjawab, atau tidak ada siapa pun jika siaran tidak memiliki Agen.
4. Titik Masuk yang spesifik cocok. Aturan kata kunci mengalahkan aturan komentar, yang mengalahkan aturan pengikut. Di antara dua aturan sejenis, aturan yang paling baru diperbarui yang menang.
5. Default saluran untuk saluran tempat pesan tiba. Default yang dicakup ke nomor spesifik yang ditulis oleh kontak mengalahkan default seluruh saluran.
6. Tidak ada yang cocok — pesan mendarat di kotak masuk untuk tim Anda dan tidak ada asisten yang membalas.

Dua hal melunakkan langkah 6. Akun dengan tepat satu Agen aktif dan tidak ada default yang dikonfigurasi untuk saluran tersebut masih mendapatkan Agen tersebut sebagai penjawab, sehingga akun baru yang menghubungkan WhatsApp dan mengirim pesan uji tidak akan mendapatkan keheningan. Batas bawah itu tidak pernah berlaku untuk saluran yang memiliki aturan kata kunci (di sana, pesan yang tidak cocok dengan kata kunci apa pun sengaja dibiarkan untuk manusia) dan tidak pernah menimpa saluran yang Anda atur ke tidak ada siapa pun (lihat Meninggalkan saluran tanpa ada yang menjawab).

Apakah tangga tersebut aktif untuk suatu akun dilaporkan oleh GET /entry-points/routing-status. Saat ini tangga tersebut aktif untuk setiap akun; panggilan tersebut ada agar integrasi dapat memeriksa alih-alih berasumsi.

Objek Titik Masuk #

{
  "id": "ep3KmQ8vTzXr5nWd",
  "type": "keyword",
  "channels": ["whatsapp", "instagram"],
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "enabled": true,
  "match_config": {
    "keywords": ["pricing", "quote"]
  },
  "first_response_mode": null,
  "first_response_exact_text": null,
  "public_comment_reply_exact_text": null,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

Tipe aturan #

Aturan kata kunci pada saluran tanpa default saluran juga berfungsi sebagai gerbang: pesan yang tidak cocok dengan kata kunci apa pun tidak akan mendapatkan balasan otomatis dan langsung masuk ke kotak masuk Anda, bahkan pada akun dengan satu Agen.

Arahkan saluran ke Agen #

PUT /entry-points/channel-defaults — menjadikan satu Agen sebagai penjawab untuk kontak baru di suatu saluran. Agen lain yang saat ini ditetapkan sebagai default saluran tersebut akan diberhentikan dalam panggilan yang sama, sehingga suatu saluran selalu memiliki tepat satu penjawab. Menetapkan Agen yang sudah menjadi default tidak akan mengubah apa pun.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ channel: "instagram", agent_id: "ag7HkQ2ZpLxR3mNb" }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb"},
)
data = res.json()

Respons

{
  "success": true,
  "entry_point_id": "ep3KmQ8vTzXr5nWd",
  "disabled_entry_point_ids": ["epPrevious1234"]
}

entry_point_id adalah aturan yang sekarang berlaku; disabled_entry_point_ids mencantumkan aturan apa pun yang diberhentikan untuk memberi ruang baginya (kosong jika tidak ada yang diganti). Hanya kontak yang belum pernah Anda ajak bicara yang terpengaruh — siapa pun yang sudah dalam percakapan dengan Agen akan tetap bersama Agen tersebut.

400 berarti channel atau agent_id tidak ada, Agen tersebut milik akun lain, atau phone_number bukan salah satu nomor Anda yang terhubung.

Lihat siapa yang menjawab setiap saluran #

GET /entry-points/channel-defaults — setiap default saluran pada akun, yang terbaru terlebih dahulu, termasuk yang sudah tidak aktif (enabled: false) dan saluran yang sengaja diatur ke tidak ada (agent_id: ""). Filter pada enabled sendiri untuk gambaran saat ini.

cURL

curl "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Respons

{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": {},
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    },
    {
      "id": "epAEnhHoozpoGVze",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "agRotterdamBranch",
      "enabled": true,
      "match_config": { "phone_numbers": ["+31685101091"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}

Ini adalah pembacaan seluruh akun. Mencantumkan aturan satu Agen dengan GET /agents/{agentId}/entry-points tidak dapat menampilkan saluran yang diatur ke tidak ada, karena aturan tersebut bukan milik Agen mana pun.

Meninggalkan saluran tanpa ada yang menjawab #

DELETE /entry-points/channel-defaults?channel=instagram — menghentikan default seluruh saluran untuk satu saluran. Saluran dinamai sebagai parameter kueri, bukan di dalam body. Tambahkan &phone_number=%2B31685101091 untuk menghapus hanya default nomor tersebut dan membiarkan nomor tersebut kembali ke siapa pun yang menjawab saluran tersebut.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    params={"channel": "instagram"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Respons

{ "success": true, "disabled_entry_point_ids": ["ep3KmQ8vTzXr5nWd"] }

Aman untuk diulangi: menghapus saluran yang tidak memiliki default adalah 200 dengan daftar kosong. Menghapus berarti membatalkan pengaturan, bukan membungkam — pada akun dengan tepat satu Agen aktif, saluran yang tidak dikonfigurasi masih akan kembali ke Agen tersebut. Untuk menjaga AI agar tidak berada di saluran sama sekali, pilih Tidak ada yang menjawab untuk saluran tersebut di panel Siapa yang Menjawab Percakapan Baru di aplikasi (yang menulis default “tidak ada” eksplisit yang tidak akan pernah ditimpa oleh fallback), atau jeda Agen dengan PATCH /agents/{agentId}/active.

Satu Agen per nomor WhatsApp #

Perutean dilakukan per saluran secara default: semua nomor WhatsApp Anda berbagi satu penjawab. Dengan dua nomor atau lebih yang terhubung di WhatsApp Business atau WhatsApp Web, default dapat dicakup ke satu nomor saja, sehingga bisnis dengan satu nomor per cabang atau merek dapat memberikan Agennya sendiri di dalam satu akun.

Kirim phone_number dengan panggilan set:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "agent_id": "agRotterdamBranch",
    "phone_number": "+31685101091"
  }'

• Nomor tersebut harus merupakan salah satu nomor yang terhubung di saluran tersebut, ditulis sebagaimana ditampilkan di bawah nomor yang terhubung (E.164 dengan +); selain itu akan dianggap sebagai 400.
• Aturan disimpan sebagai default saluran dengan match_config.phone_numbers: ["+31685101091"]. Pesan yang masuk ke nomor tersebut akan diteruskan ke Agennya; setiap nomor lainnya akan terus mengikuti default seluruh saluran.
• Mengatur atau menghapus default seluruh saluran tidak akan memengaruhi aturan yang dicakup oleh nomor, begitu pula sebaliknya. Hapus aturan milik nomor tertentu dengan DELETE /entry-points/channel-defaults?channel=whatsapp_web&phone_number=%2B31685101091.
• Balasan selalu dikirim dari nomor yang dihubungi oleh kontak, sehingga kontak tetap berkomunikasi dengan nomor yang sama dan Agen yang sama.

Menambahkan aturan yang lebih spesifik #

POST /agents/{agentId}/entry-points — membuat aturan kata kunci, komentar, atau pengikut (atau default saluran, meskipun PUT /entry-points/channel-defaults adalah pilihan yang lebih baik untuk itu karena secara otomatis menonaktifkan penjawab sebelumnya untuk Anda). Agen di dalam jalur selalu diutamakan: aturan tidak akan pernah bisa dibuat untuk Agen yang berbeda dari yang ada di URL.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "keyword",
      channels: ["whatsapp", "instagram"],
      match_config: { keywords: ["pricing", "quote"] },
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "type": "keyword",
        "channels": ["whatsapp", "instagram"],
        "match_config": {"keywords": ["pricing", "quote"]},
    },
)
data = res.json()

Respons (201)

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Aturan komentar-ke-DM yang hanya bereaksi terhadap komentar yang bertuliskan “LINK” pada dua kiriman tertentu, menunggu dua menit, dan mengirimkan pesan pertama yang tetap:

{
  "type": "instagram_comment",
  "channels": ["instagram"],
  "match_config": {
    "keywords": ["LINK"],
    "post_ids": ["17895695668004550", "17841400008460056"],
    "delay_minutes": 2
  },
  "first_response_mode": "exact_text",
  "first_response_exact_text": "Hi {{first_name}}, here is the link you asked for: https://example.com/guide",
  "public_comment_reply_exact_text": "Sent you a DM!"
}

Biarkan keywords kosong untuk mengirim DM kepada siapa pun yang berkomentar pada kiriman yang dipantau, dan post_ids kosong untuk memantau setiap kiriman. 400 akan menyebutkan apa yang salah: type yang tidak dikenal, channels yang kosong, aturan kata kunci tanpa kata kunci, atau aturan komentar yang tidak mencantumkan salurannya sendiri.

Mencantumkan aturan Agen #

GET /agents/{agentId}/entry-points — aturan yang mengirimkan percakapan ke Agen ini, diurutkan dari yang terbaru: default salurannya, aturan kata kunci, aturan komentar, dan aturan pengikut. Aturan yang dinonaktifkan juga akan muncul kembali dengan enabled: false.

cURL

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Respons

{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "keyword",
      "channels": ["whatsapp", "instagram"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": { "keywords": ["pricing", "quote"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}

Mengubah aturan #

PUT /entry-points/{entryPointId} — mengubah satu aturan. Kirimkan hanya bidang yang ingin Anda ubah; pengaturan bertingkat dapat diakses per bagian dengan kunci bertitik seperti "match_config.keywords". Setiap kali perubahan menyentuh type, channels, atau match_config, seluruh aturan akan diperiksa ulang, sehingga pengeditan parsial tidak akan pernah meninggalkan aturan yang tidak dapat digunakan (mengalihkan type ke keyword tanpa menyertakan kata kunci akan ditolak). Mengirim agent_id akan menyerahkan aturan tersebut ke Agen Anda yang lain; nilai kosong akan ditolak. Bidang kepemilikan dan identitas akan diabaikan.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "match_config": { "keywords": ["pricing", "quote", "demo"] } }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ match_config: { keywords: ["pricing", "quote", "demo"] } }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"match_config": {"keywords": ["pricing", "quote", "demo"]}},
)
data = res.json()

Respons

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Pengeditan umum lainnya: { "enabled": false } menonaktifkan aturan tanpa menghapusnya, dan { "agent_id": "agOtherAgent" } memindahkannya ke Agen yang berbeda. Isi kosong akan mengembalikan 400 dengan "No fields to update".

Menghapus aturan #

DELETE /entry-points/{entryPointId} — menghapus aturan secara permanen. Tidak ada hal lain yang merujuk ke Titik Masuk, jadi tidak ada yang perlu dilepaskan terlebih dahulu.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Respons

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Untuk menghentikan aturan agar tidak berjalan namun tetap menyimpannya, atur enabled ke false sebagai gantinya. Default saluran khususnya biasanya dinonaktifkan alih-alih dihapus, yang merupakan fungsi dari DELETE /entry-points/channel-defaults.

Memeriksa apakah perutean aktif #

GET /entry-points/routing-status — mengembalikan apakah tangga Titik Masuk (Entry Points) memutuskan siapa yang menjawab di akun ini. Dapat dibaca dengan akses lihat, sehingga rekan tim melihat jawaban yang sama dengan pemiliknya.

curl "https://api.youraiconnector.com/v1/entry-points/routing-status?apiKey=YOUR_API_KEY"

{ "success": true, "cutover_enabled": true }

Ini true di setiap akun saat ini. Panggilan tersebut disimpan agar integrasi dapat memverifikasi sebelum memberi tahu seseorang bahwa perubahan perutean mereka sudah aktif, alih-alih berasumsi.

Panggilan lama yang berbentuk kampanye #

Dua titik akhir dari sebelum adanya Agen masih berfungsi untuk akun yang diatur berdasarkan kampanye. Integrasi baru sebaiknya menggunakan panggilan default saluran di atas.

• PUT /channel-routing/{channel} dengan { "campaignId": "cp5NbV8xQrT2wYzA" } — menamai kampanye, dan Agen kampanye tersebut menjadi penjawab saluran. { "campaignId": null } mengosongkan saluran. Kampanye khusus keluar ditolak karena tidak memiliki perilaku masuk untuk ditawarkan.
• POST /channel-routing/clear dengan { "channels": ["whatsapp", "instagram"] } — membebaskan beberapa saluran dari Agen mana pun yang menjawabnya dalam satu panggilan, biasanya sebelum mengarahkannya ke tempat lain. Respons mencantumkan released_channels, yaitu saluran yang benar-benar memiliki penjawab.

Keduanya tidak disetel alih-alih dibungkam: pada akun dengan tepat satu Agen aktif, saluran yang dibebaskan masih akan kembali ke Agen tersebut.

Kesalahan API Titik Masuk #

Titik akhir Titik Masuk mengembalikan amplop kesalahan standar:

{
  "success": false,
  "error": "Entry point not found"
}

Kode bersama yang dapat dikembalikan oleh setiap endpoint — 401, 403 (paket Anda tidak menyertakan akses API), 429 (batas kecepatan) dan 500 — tercantum beserta panduan percobaan ulang di Kesalahan & Penomoran Halaman.

Langkah berikutnya #

• Titik Masuk — konsep, jenis aturan, dan panel Siapa yang Menjawab Percakapan Baru di aplikasi.
• API Agen AI — membuat dan mengonfigurasi Agen yang dituju oleh aturan-aturan ini.
• API Saluran — menghubungkan saluran itu sendiri.
• Otomatisasi Komentar-ke-DM — apa yang dilakukan aturan komentar setelah dipicu.