Your AI Connector Docs

API Tim

Tim Anda adalah semua orang yang bekerja di dalam akun Anda selain Anda sendiri — admin, agen, dan penampil (read-only) — ditambah undangan yang telah Anda kirim dan departemen tempat Anda mengelompokkan mereka. API Tim adalah versi terprogram dari Pengaturan → Tim: menambah dan menghapus orang, mengatur apa yang dapat dilihat dan dilakukan oleh masing-masing orang, mengirim dan menindaklanjuti undangan, serta mengelola departemen.

Semua endpoint di bawah ini bersifat relatif terhadap URL dasar https://api.youraiconnector.com/v1. Untuk versi dasbor dari semua yang ada di halaman ini, lihat Manajemen Tim.


Autentikasi: endpoint ini memerlukan orang yang sudah masuk (signed-in)

Ini adalah satu bagian dari API yang tidak dapat digunakan oleh kunci API. Setiap endpoint /team kecuali endpoint departemen harus dipanggil dengan token ID Firebase dari sesi yang sudah masuk:

Authorization: Bearer <Firebase ID token>

Kirim kunci API sebagai gantinya dan permintaan akan ditolak dengan 401:

{
  "success": false,
  "error_code": 401,
  "error": "This endpoint requires a Firebase ID token (Authorization: Bearer <token>)."
}

Alasannya adalah endpoint ini memutuskan apa yang harus dilakukan berdasarkan siapa yang masuk: peran Anda, batasan atas dari apa yang diizinkan untuk Anda berikan kepada orang lain, dan apakah Anda saat ini sedang bekerja di dalam akun lain. Kunci API adalah integrasi, bukan orang, jadi tidak ada siapa pun yang dapat menerapkan aturan tersebut.

Dalam praktiknya, itu berarti API Tim ditujukan untuk aplikasi pihak pertama dengan pengguna Your AI Connector yang sudah masuk (lihat Autentikasi → Token ID Firebase). Integrasi server-ke-server tidak dapat mengelola anggota tim — tidak ada cara untuk membuat salah satu token ini dari luar aplikasi.

Pengecualian: keempat endpoint departemen adalah endpoint API biasa. Endpoint tersebut menerima kunci API Anda persis seperti bagian API lainnya, serta sesi yang sudah masuk.

Setiap respons di halaman ini mengikuti amplop (envelope) yang biasa: success: true ditambah kolom endpoint di tingkat teratas, atau success: false dengan error dan error_code ketika terjadi kesalahan.


Peran dan izin

Setiap anggota tim memiliki satu peran, yang menetapkan akses default mereka di 12 area aplikasi. Anda kemudian dapat mengganti (override) pengaturan untuk area individu.

Peran Nilai Ringkasan
Admin admin Semuanya kecuali tindakan tingkat penagihan pemilik.
Editor editor Dapat membuat dan mengubah berbagai hal. Ditampilkan sebagai Agen di aplikasi.
Viewer viewer Hanya baca (read-only).

Setiap area diatur ke salah satu dari empat tingkat: none (tersembunyi), view (hanya baca), edit (buat dan ubah), full (termasuk menghapus).

Area Admin Editor Viewer
campaigns full edit view
contacts full edit view
messages full edit view
appointments full edit view
settings edit view none
billing edit none none
team_management edit none none
analytics full view view
phone_numbers edit none none
integrations edit none none
faqs full edit view
daily_summaries full view view

Untuk menyimpang dari default peran, kirim permission_overrides — sebuah array objek { "area": ..., "level": ... }. Setiap entri menggantikan default peran untuk area tersebut; semua yang tidak Anda cantumkan akan tetap menggunakan default peran.

"permission_overrides": [
  { "area": "analytics", "level": "full" },
  { "area": "billing", "level": "none" }
]

Siapa yang dapat memanggil endpoint ini

  • Pemilik akun selalu dapat melakukan segalanya.
  • Anggota tim memerlukan team_management di view untuk membaca daftar anggota dan daftar undangan, serta di edit untuk menambah, mengubah, menangguhkan, menghapus, mengundang, membatalkan, atau mengirim ulang. Admin memiliki edit secara default; editor dan penampil memiliki none, jadi secara default hanya admin yang dapat mengelola tim.
  • Tidak ada yang dapat memberikan akses di atas akses mereka sendiri. Jika Anda mencoba memberikan level kepada seseorang yang tidak Anda miliki sendiri — atau mengedit, menangguhkan, atau menghapus seseorang yang aksesnya sudah lebih luas daripada Anda — permintaan akan ditolak dengan 403 dan pesan yang menyebutkan area tersebut.

Objek anggota tim

GET /team/members mengembalikan salah satu dari ini per anggota:

Bidang Tipe Deskripsi
member_uid string ID pengguna anggota itu sendiri. Ini adalah {memberUid} di jalur di bawah.
account_owner_uid string Akun tempat mereka menjadi anggota.
member_email string Alamat email mereka.
member_display_name string Nama yang ditampilkan untuk mereka di aplikasi.
role string admin, editor atau viewer.
permission_overrides array Pengecualian per-area mereka. [] jika mereka murni menggunakan default peran.
status string active atau suspended.
auto_assign_enabled boolean | null Apakah kontak baru dapat ditetapkan secara otomatis kepada mereka. null berarti tidak pernah diubah, yang berperilaku sebagai true.
created_by string Siapa yang menambahkan mereka.
created_at string | null Stempel waktu ISO 8601.
updated_at string | null Stempel waktu ISO 8601.

Anggota yang dihapus tidak dikembalikan — daftar ini hanya berisi anggota aktif dan yang ditangguhkan.

Batas visibilitas hanya bersifat tulis di sini. contact_scope, contact_scope_axes dan sub_account_access (lihat Membatasi apa yang dapat dilihat anggota) dapat diatur saat membuat, memperbarui, dan mengundang, tetapi endpoint ini tidak mengembalikannya.


Daftar anggota tim

GET /team/members

Mengembalikan daftar anggota beserta jumlah kursi paket Anda, sehingga Anda dapat menampilkan “3 dari 5 kursi” dan mengetahui kapan undangan akan ditolak.

cURL

curl "https://api.youraiconnector.com/v1/team/members" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/members", {
  headers: { Authorization: `Bearer ${idToken}` },
});
const { members, seat_limit, seats_used } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/team/members",
    headers={"Authorization": f"Bearer {id_token}"},
)
data = res.json()

Respons

{
  "success": true,
  "members": [
    {
      "account_owner_uid": "owner_uid_123",
      "member_uid": "uid_alice",
      "member_email": "alice@example.com",
      "member_display_name": "Alice Chen",
      "role": "admin",
      "permission_overrides": [],
      "status": "active",
      "auto_assign_enabled": true,
      "created_by": "owner_uid_123",
      "created_at": "2026-05-01T10:00:00.000Z",
      "updated_at": "2026-06-02T09:15:00.000Z"
    }
  ],
  "seat_limit": 5,
  "seats_used": 3
}

seat_limit adalah null ketika paket Anda tidak memiliki batas kursi. seats_used hanya menghitung anggota aktif — menangguhkan atau menghapus seseorang akan segera mengosongkan kursi mereka.


Menambahkan anggota tim secara langsung

POST /team/members

Memasukkan seseorang ke tim Anda secara langsung, tanpa undangan.

Ini tidak mengirim email apa pun. Tidak ada yang diberi tahu bahwa mereka telah ditambahkan, dan jika mereka belum memiliki login Your AI Connector, akun yang dibuat untuk mereka tidak memiliki kata sandi, sehingga mereka tidak dapat masuk sampai mereka menyetel ulang kata sandi tersebut. Gunakan Kirim undangan kecuali Anda memiliki cara sendiri untuk memberi tahu orang tersebut dan membantu mereka masuk.

Bidang permintaan

Bidang Wajib Deskripsi
email Ya Alamat email rekan tim.
display_name Ya Nama yang ditampilkan untuk mereka di aplikasi.
role Ya admin, editor atau viewer.
permission_overrides Tidak Pengecualian per-area terhadap default peran.
contact_scope Tidak all atau assigned — lihat Membatasi apa yang dapat dilihat anggota.
contact_scope_unassigned Tidak Dengan assigned, izinkan mereka juga melihat kontak yang belum dimiliki siapa pun.
contact_scope_axes Tidak Batasi mereka pada agen, saluran, atau departemen tertentu.
sub_account_access Tidak Khusus agensi — sub-akun klien mana yang boleh mereka buka.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/members" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sam@example.com",
    "display_name": "Sam Rivera",
    "role": "editor"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/members", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${idToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "sam@example.com",
    display_name: "Sam Rivera",
    role: "editor",
  }),
});
const { member_uid } = await res.json();

Respons201 Created

{
  "success": true,
  "team_member_id": "owner_uid_123_uid_sam",
  "member_uid": "uid_sam",
  "message": "Team member created successfully."
}
Status Kapan
400 email, display_name atau role tidak ada, peran bukan salah satu dari ketiganya, atau Anda mencoba menambahkan diri sendiri.
403 Anda tidak memiliki izin untuk mengelola tim, atau Anda mencoba memberikan akses yang lebih tinggi dari milik Anda sendiri.
409 Orang tersebut sudah menjadi anggota aktif tim Anda.
429 Kursi tim paket Anda sudah penuh.

Menambahkan seseorang yang sebelumnya ditangguhkan atau dihapus akan mengaktifkan kembali mereka alih-alih gagal.


Memperbarui anggota tim

PATCH /team/members/{memberUid}

Mengubah peran, izin, visibilitas, akses klien, atau apakah anggota tersebut berpartisipasi dalam penugasan kontak otomatis. Kirim hanya bidang yang ingin Anda ubah; apa pun yang Anda abaikan akan tetap mempertahankan nilainya saat ini.

Bidang permintaan

Bidang Deskripsi
role admin, editor atau viewer.
permission_overrides Menggantikan seluruh daftar pengecualian mereka. Kirim [] untuk mengembalikan mereka ke default peran murni.
status Hanya active yang diterima, untuk mengaktifkan kembali anggota yang ditangguhkan. Untuk menangguhkan seseorang, gunakan endpoint tangguhkan.
auto_assign_enabled true atau false.
contact_scope all atau assigned.
contact_scope_unassigned true atau false.
contact_scope_axes Lihat Membatasi apa yang dapat dilihat anggota.
sub_account_access Khusus agensi.

Ini adalah satu-satunya endpoint di mana null berarti “hapus”. Mengirim "contact_scope": null, "contact_scope_axes": null atau "sub_account_access": null akan menghapus batasan tersebut sepenuhnya dan mengembalikan anggota agar dapat melihat semuanya. Saat membuat dan mengundang, null hanya berarti “tidak disediakan”.

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/team/members/uid_sam" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin",
    "permission_overrides": [{ "area": "billing", "level": "none" }]
  }'

Respons

{
  "success": true,
  "message": "Team member updated successfully."
}
Status Kapan
400 Nilai status atau auto_assign_enabled tidak valid, atau Anda mencoba mengaktifkan kembali anggota yang telah dihapus (anggota yang dihapus harus diundang kembali).
403 Anda tidak memiliki izin, atau perubahan tersebut akan mengedit atau membuat akses yang lebih luas daripada milik Anda sendiri.
404 Anggota tim tersebut tidak ada.

Menangguhkan anggota tim

POST /team/members/{memberUid}/suspend

Menangguhkan seseorang: mereka tetap berada di tim tetapi kehilangan akses. Gunakan ini alih-alih menghapus jika penangguhan bersifat sementara — aktifkan kembali mereka dengan PATCH /team/members/{memberUid} dan {"status": "active"}.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/members/uid_sam/suspend" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Respons

{
  "success": true,
  "message": "Team member suspended successfully."
}

Anggota yang ditangguhkan mengosongkan kursi mereka, sehingga Anda dapat mengundang orang lain sebagai penggantinya. Akses mereka berakhir saat token sesi mereka saat ini diperbarui, yang dapat memakan waktu hingga satu jam — hapus mereka jika Anda ingin akses tersebut segera berakhir.

Status Kapan
400 Anda mencoba menangguhkan pemilik akun, atau anggota yang sudah ditangguhkan atau dihapus.
403 Akses mereka lebih luas daripada milik Anda.
404 Anggota tim tersebut tidak ada.

Menghapus anggota tim

DELETE /team/members/{memberUid}

Menghapus seseorang dari tim Anda dan mengosongkan kursinya. Mereka akan dikeluarkan (signed out) dan kehilangan akses ke akun Anda; login mereka sendiri tidak akan terpengaruh.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/team/members/uid_sam" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Respons

{
  "success": true,
  "message": "Team member removed successfully."
}

Penghapusan bersifat permanen dari sisi Anda: anggota yang telah dihapus tidak dapat diaktifkan kembali dengan endpoint pembaruan — undang mereka kembali jika Anda berubah pikiran. Email mereka juga akan dihapus dari daftar notifikasi akun Anda.

Status Kapan
400 Anda mencoba menghapus pemilik akun.
403 Akses mereka lebih luas daripada akses Anda.
404 Anggota tim tersebut tidak ada.

Membatasi apa yang dapat dilihat anggota

Tiga kolom opsional, yang diterima pada tambah, perbarui, dan undang, menentukan seberapa banyak bagian akun yang dapat dilihat seseorang. Kolom-kolom ini bersifat kumulatif: anggota yang dibatasi pada lebih dari satu kategori akan dibatasi oleh semuanya.

contact_scopeall (default: setiap kontak dan percakapan) atau assigned (hanya yang ditugaskan kepada mereka). Dengan assigned, tambahkan "contact_scope_unassigned": true untuk juga mengizinkan mereka melihat kontak yang belum dimiliki siapa pun.

contact_scope_axes — membatasi mereka pada agen, saluran, atau departemen tertentu:

Kolom Tipe Deskripsi
agents string[] ID Agen. Mereka hanya melihat obrolan yang diarahkan ke salah satu agen ini. Maksimal 200.
channels string[] Nama saluran — whatsapp, whatsapp_web, sms, instagram, instagram_private, messenger, facebook, chat_widget, telegram, line, viber, tiktok, imessage, email, linkedin, skool, custom, custom_channel. Maksimal 200.
departments string[] ID Departemen (lihat Departemen). Mereka hanya melihat prospek yang diajukan di bawah departemen tersebut. Maksimal 200.
include_unrouted boolean Dengan agents diatur, tampilkan juga obrolan yang tidak ditangani oleh agen mana pun. Nonaktif secara default. Diabaikan saat agents kosong.
include_undepartmented boolean Dengan departments diatur, tampilkan juga obrolan yang tidak berada di departemen mana pun. Nonaktif secara default. Diabaikan saat departments kosong.

ID agen dan departemen tidak diperiksa saat Anda menyimpannya — ID yang tidak ada hanya tidak akan mencocokkan apa pun, yang akan muncul sebagai kotak masuk kosong alih-alih kesalahan. Nama saluran diperiksa: nama yang tidak dikenali akan ditolak dengan 400.

Tidak satu pun dari ketiga hal ini dapat diatur pada pemilik akun — permintaan tersebut akan ditolak dengan 400.


Daftar undangan

GET /team/invites

Undangan yang telah Anda kirim, diurutkan dari yang terbaru, sehingga Anda dapat melihat siapa yang belum menerima undangan tersebut.

Parameter kueri

Parameter Wajib Deskripsi
status Tidak Hanya mengembalikan undangan dalam status ini — pending, accepted, declined, cancelled atau expired.

cURL

curl "https://api.youraiconnector.com/v1/team/invites?status=pending" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Respons

{
  "success": true,
  "invites": [
    {
      "id": "inv_abc123",
      "account_owner_uid": "owner_uid_123",
      "account_owner_display_name": "Acme Ltd",
      "invitee_email": "sam@example.com",
      "invitee_uid": null,
      "role": "editor",
      "permission_overrides": [],
      "status": "pending",
      "created_by": "owner_uid_123",
      "created_at": "2026-06-10T12:00:00.000Z",
      "expires_at": "2026-06-17T12:00:00.000Z",
      "responded_at": null
    }
  ]
}

Token undangan tidak pernah dikembalikan — token tersebut hanya ada di dalam email yang dikirimkan.


Mengirim undangan

POST /team/invites

Mengirim email undangan kepada seseorang untuk bergabung dengan tim Anda. Ini adalah cara umum untuk menambahkan rekan tim: mereka mengeklik tautan, masuk sebagai diri mereka sendiri, dan menerima undangan. Jika mereka belum memiliki akun Your AI Connector, akun akan dibuatkan untuk mereka dan email tersebut akan memandu mereka dalam mengatur kata sandi.

Bidang permintaan

Bidang Wajib Deskripsi
email Ya Ke mana undangan harus dikirim.
role Ya admin, editor atau viewer.
permission_overrides Tidak Pengecualian per-area, diterapkan saat mereka menerima undangan.
contact_scope Tidak Diterapkan saat mereka menerima undangan.
contact_scope_unassigned Tidak Diterapkan saat mereka menerima undangan.
contact_scope_axes Tidak Diterapkan saat mereka menerima undangan.
sub_account_access Tidak Hanya untuk agensi. Diterapkan saat mereka menerima undangan.

Mengatur izin di awal berarti Anda tidak perlu mengedit anggota setelahnya — semuanya disalin ke keanggotaan mereka saat mereka menerima undangan.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "sam@example.com", "role": "editor" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/invites", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${idToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "sam@example.com", role: "editor" }),
});
const { invite_id } = await res.json();

Respons201 Created

{
  "success": true,
  "invite_id": "inv_abc123",
  "message": "Team invite sent successfully."
}

Hal-hal yang perlu direncanakan

  • Undangan kedaluwarsa setelah 7 hari. Undangan yang kedaluwarsa dapat dikirim ulang, yang akan memulai periode 7 hari yang baru.
  • Undangan yang tertunda menggunakan satu kursi. Berbeda dengan menambahkan anggota secara langsung, pemeriksaan kursi di sini menghitung anggota aktif ditambah undangan yang tertunda, sehingga akun yang semua kursinya sudah terisi akan ditolak sebelum email dikirim.
  • 20 undangan per hari, dihitung per akun untuk pengiriman maupun pengiriman ulang.
Status Kapan
400 email tidak ada atau peran tidak valid.
403 Anda tidak memiliki izin untuk mengelola tim, atau Anda mencoba memberikan akses yang melebihi tingkat akses Anda sendiri.
409 Undangan tertunda untuk email tersebut sudah ada, atau orang tersebut sudah ada di tim Anda.
429 Kursi tim paket Anda sudah penuh, atau Anda telah mencapai batas 20 undangan per hari. Pesan error akan memberi tahu yang mana penyebabnya.

Membatalkan undangan

DELETE /team/invites/{inviteId}

Membatalkan undangan sebelum diterima. Tautan di dalam email tidak akan berfungsi lagi.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/team/invites/inv_abc123" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Respons

{
  "success": true,
  "message": "Team invite cancelled."
}

Undangan pending maupun expired dapat dibatalkan. Undangan yang sudah diterima, ditolak, atau dibatalkan akan mengembalikan 400; undangan yang bukan milik Anda akan mengembalikan 403; ID yang tidak dikenal akan mengembalikan 404.


Mengirim ulang undangan

POST /team/invites/{inviteId}/resend

Mengirim ulang email undangan — untuk kasus di mana email terlewat atau masuk ke spam. Berfungsi pada undangan pending dan expired, serta mengatur ulang masa berlaku menjadi 7 hari dari sekarang.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/inv_abc123/resend" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Respons

{
  "success": true,
  "message": "Team invite resent successfully."
}

Email baru menyertakan tautan baru, dan tautan lama tetap berfungsi, sehingga orang yang menemukan email pertama di kemudian hari tidak akan terkendala. Mengirim ulang tetap dihitung dalam batas 20 undangan per hari seperti pengiriman biasa, dan mengaktifkan kembali undangan yang kedaluwarsa akan memeriksa ulang kuota kursi Anda — paket yang penuh akan ditolak dengan 429.


Menerima undangan

POST /team/invites/accept

Menerima undangan dengan token dari email undangan, yang akan memasukkan orang yang sedang masuk ke tim akun tersebut.

Ini adalah tindakan identitas Anda sendiri. Masuklah sebagai diri sendiri — tindakan ini sengaja ditolak dengan 403 saat Anda sedang bekerja di dalam akun orang lain.

Bidang permintaan

Bidang Wajib Deskripsi
invite_token Ya Token dari tautan email undangan.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/accept" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invite_token": "1f4c…" }'

Respons

{
  "success": true,
  "team_member_id": "owner_uid_123_uid_sam",
  "account_owner_uid": "owner_uid_123",
  "message": "Team invite accepted successfully."
}
Status Kapan
400 invite_token tidak ada, atau undangan tersebut ditujukan untuk akun Anda sendiri.
403 Sesi sedang bekerja di dalam akun lain, atau undangan dikirim ke alamat email yang berbeda dengan yang Anda gunakan untuk masuk.
404 Undangan tidak ada atau sudah digunakan.
429 Kursi akun penuh antara waktu undangan dan penerimaan Anda.
504 Undangan telah kedaluwarsa. Minta pengirim untuk mengirimnya kembali.

Menolak undangan

POST /team/invites/decline

Menolak undangan dengan token dari email. Seperti halnya menerima, ini adalah tindakan identitas Anda sendiri dan akan ditolak saat Anda sedang bekerja di dalam akun lain.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/decline" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invite_token": "1f4c…" }'

Respons

{
  "success": true,
  "message": "Team invite declined."
}

Departemen

Departemen adalah grup bernama dari tim Anda — Penjualan, Dukungan pelanggan, SDM. Departemen memberikan tim pemilik kepada prospek, dapat mengklaim percakapan baru secara mandiri, dan dapat digunakan untuk membatasi apa yang dilihat oleh anggota.

Keempat endpoint ini memerlukan kunci API. Berbeda dengan bagian lain di halaman ini, endpoint ini melakukan autentikasi seperti endpoint lainnya di API (lihat Autentikasi). Sesi yang masuk juga berfungsi: membaca memerlukan contacts di view, dan membuat, mengubah, atau menghapus memerlukan team_management di edit.

Objek departemen

Bidang Tipe Deskripsi
id string ID departemen. Gunakan di contact_scope_axes.departments dan di jalur di bawah ini.
name string Nama tim. Maksimal 60 karakter, unik di akun.
color string | null Warna aksen sebagai #rrggbb, atau null.
member_uids string[] Anggota tim di departemen ini. Dapat mencakup pemilik akun.
auto_assign_enabled boolean Apakah prospek yang dimasukkan ke departemen ini juga diserahkan kepada seseorang di dalamnya. false berarti departemen bekerja dari antrean bersama.
routing_agents string[] Percakapan baru yang ditangani oleh Agen AI ini secara otomatis dimasukkan ke departemen ini. Kosong berarti tidak ada aturan agen.
routing_channels string[] Percakapan baru di saluran ini secara otomatis dimasukkan ke sini. Kosong berarti tidak ada aturan saluran.
created_by string | null Siapa yang membuatnya.

Ketika routing_agents dan routing_channels keduanya diatur, percakapan harus cocok dengan keduanya agar dapat dimasukkan ke sini — begitulah cara Anda memberikan satu tim “agen dukungan, tetapi hanya di WhatsApp”.

Satu akun dapat memiliki hingga 50 departemen.

Daftar departemen

GET /team/departments

curl "https://api.youraiconnector.com/v1/team/departments?apiKey=YOUR_API_KEY"

Respons

{
  "success": true,
  "departments": [
    {
      "id": "dep_abc123",
      "name": "Sales",
      "color": "#2f6fed",
      "member_uids": ["uid_alice", "uid_bob"],
      "auto_assign_enabled": true,
      "routing_agents": [],
      "routing_channels": ["whatsapp"],
      "created_by": "owner_uid_123"
    }
  ]
}

Membuat departemen

POST /team/departments

Bidang permintaan

Bidang Wajib Deskripsi
name Ya Maksimal 60 karakter. Tidak boleh sama dengan departemen yang sudah ada.
color Tidak #rrggbb hex, atau null.
member_uids Tidak Siapa saja yang ada di dalamnya. Setiap UID harus merupakan pemilik akun atau anggota tim yang aktif.
auto_assign_enabled Tidak Default ke true.
routing_agents Tidak ID Agen yang obrolan barunya masuk ke sini.
routing_channels Tidak Nama saluran yang obrolan barunya masuk ke sini — kosakata yang sama dengan contact_scope_axes.channels.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/departments?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice", "uid_bob"],
    "routing_channels": ["whatsapp"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/departments", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Sales",
    color: "#2f6fed",
    member_uids: ["uid_alice", "uid_bob"],
    routing_channels: ["whatsapp"],
  }),
});
const { department } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/team/departments",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "Sales",
        "color": "#2f6fed",
        "member_uids": ["uid_alice", "uid_bob"],
        "routing_channels": ["whatsapp"],
    },
)
department = res.json()["department"]

Respons201 Created

{
  "success": true,
  "department": {
    "id": "dep_abc123",
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice", "uid_bob"],
    "auto_assign_enabled": true,
    "routing_agents": [],
    "routing_channels": ["whatsapp"],
    "created_by": "owner_uid_123"
  }
}
Status Kapan
400 name hilang atau terlalu panjang, color bukan #rrggbb, nama saluran tidak dikenali, UID yang terdaftar bukan anggota aktif tim ini, atau Anda sudah memiliki 50 departemen.
409 Departemen dengan nama tersebut sudah ada.

Memperbarui departemen

PATCH /team/departments/{departmentId}

Mengubah departemen. Hanya bidang yang Anda kirim yang akan diubah.

curl -X PATCH "https://api.youraiconnector.com/v1/team/departments/dep_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "member_uids": ["uid_alice"], "auto_assign_enabled": false }'

Respons

{
  "success": true,
  "department": {
    "id": "dep_abc123",
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice"],
    "auto_assign_enabled": false,
    "routing_agents": [],
    "routing_channels": ["whatsapp"],
    "created_by": "owner_uid_123"
  }
}

Mengirim kolom yang tidak dikenali akan mengembalikan 400; departemen yang tidak diketahui akan mengembalikan 404; nama yang bentrok dengan departemen lain akan mengembalikan 409.

Menghapus departemen

DELETE /team/departments/{departmentId}

curl -X DELETE "https://api.youraiconnector.com/v1/team/departments/dep_abc123?apiKey=YOUR_API_KEY"

Respons

{
  "success": true,
  "deleted": "dep_abc123"
}

Menghapus departemen yang membatasi akses seseorang akan ditolak. Respons 400 menyebutkan anggota yang visibilitasnya dibatasi pada departemen tersebut, sehingga Anda dapat mengubah cakupannya terlebih dahulu. Hal ini disengaja: menghapus batasan secara diam-diam akan memberikan mereka akses ke seluruh basis pelanggan Anda tanpa ada pemberitahuan bahwa hal itu terjadi.

Kontak yang tersimpan di bawah departemen yang dihapus tidak akan diubah — mereka hanya akan berhenti menampilkan departemen, dan saat Anda menyimpannya kembali, departemen tersebut akan terpasang.


Periksa izin Anda sendiri

GET /team/permissions

Mengembalikan apa yang diizinkan untuk dilakukan oleh orang yang masuk di akun tempat mereka bekerja saat ini. Gunakan ini untuk menyembunyikan tombol yang tidak dapat digunakan oleh anggota, alih-alih membiarkan mereka mengetahui batasan tersebut melalui pesan kesalahan.

cURL

curl "https://api.youraiconnector.com/v1/team/permissions" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Respons — pemilik akun

{
  "success": true,
  "role": "owner",
  "is_team_mode": false,
  "permissions": {
    "campaigns": "full",
    "contacts": "full",
    "messages": "full",
    "appointments": "full",
    "settings": "full",
    "billing": "full",
    "team_management": "full",
    "analytics": "full",
    "phone_numbers": "full",
    "integrations": "full",
    "faqs": "full",
    "daily_summaries": "full"
  }
}

Respons — anggota tim yang bekerja di dalam akun

{
  "success": true,
  "role": "editor",
  "is_team_mode": true,
  "permissions": { "campaigns": "edit", "billing": "none", "…": "…" },
  "member": {
    "uid": "uid_sam",
    "email": "sam@example.com",
    "display_name": "Sam Rivera",
    "account_owner_uid": "owner_uid_123"
  }
}

role adalah owner ketika orang yang masuk adalah pemilik akun; jika tidak, itu adalah peran tim mereka. member hanya ada dalam mode tim, dan memuat contact_scope, contact_scope_unassigned, dan contact_scope_axes ketika keanggotaan mereka memilikinya.


Token sesi

Lima endpoint membuat token masuk sekali pakai untuk berpindah antar akun. Semuanya memberikan respons yang sama:

{
  "success": true,
  "customToken": "eyJhbGciOi…"
}

Token tersebut ditukarkan dengan sesi menggunakan SDK klien Firebase. Ini bukan kunci API dan tidak dapat dikirim sebagai kunci API, itulah sebabnya endpoint ini hanya berguna di dalam aplikasi pihak pertama.

Endpoint Fungsi Isi
POST /team/tokens/team-member Memungkinkan anggota tim mulai bekerja di dalam akun tempat mereka berada. account_owner_uid (wajib)
POST /team/tokens/return-from-team Membawa mereka kembali keluar, ke akun mereka sendiri.
POST /team/tokens/assist Memungkinkan staf Your AI Connector membuka akun pelanggan untuk membantu. Hanya untuk staf. customerUid
POST /team/tokens/return-to-admin Mengakhiri sesi bantuan dan mengembalikan staf ke akun mereka sendiri.
POST /team/tokens/agency-assist Memungkinkan agensi membuka salah satu sub-akun kliennya — atau, jika dipanggil tanpa sub-akun, kembali ke akun agensi. subAccountUid (opsional)

Masing-masing menolak dengan 403 jika sesi tidak berhak atasnya: bukan anggota akun tersebut, bukan staf, sub-akun tersebut tidak ada di agensi Anda atau belum diberikan kepada Anda, atau sesi saat ini tidak dalam mode yang diakhiri oleh endpoint.


Menetapkan peran platform

POST /team/users/{targetUid}/role

Menetapkan peran platform pengguna — User, Dev, Support, atau Agency. Ini bukan keanggotaan tim: ini adalah jenis akun Your AI Connector yang dimiliki seseorang.

Endpoint ini dibatasi untuk staf Your AI Connector, dan Dev terakhir yang tersisa tidak dapat diturunkan pangkatnya. Dicantumkan untuk kelengkapan; ini bukan bagian dari pengelolaan tim Anda sendiri.

{
  "success": true,
  "targetUid": "uid_sam",
  "role": "Agency",
  "claimUpdated": true
}
Status Kapan
400 role tidak ada atau bukan salah satu dari empat peran, atau ini akan menghapus Dev terakhir.
403 Anda bukan staf, atau sesi sedang bekerja di dalam akun lain.
404 Pengguna tidak ditemukan.

Kesalahan API Tim

Endpoint tim mengembalikan amplop kesalahan standar, selalu dengan error_code di samping status HTTP:

{
  "success": false,
  "error_code": 403,
  "error": "Cannot grant \"full\" access to \"billing\" — exceeds your own permissions."
}
Status Kapan terjadi pada endpoint tim
400 Bidang yang diperlukan tidak ada atau tidak valid, atau tindakan tidak diizinkan dalam status ini (mengaktifkan kembali anggota yang dihapus, menangguhkan pemilik, menghapus departemen yang dibatasi untuk seseorang).
401 Anda mengirim kunci API ke endpoint yang memerlukan orang yang masuk — lihat Autentikasi.
403 Anda tidak memiliki izin team_management, perubahan melebihi akses Anda sendiri, atau tindakan ditolak saat bekerja di dalam akun lain.
404 Tidak ada anggota, undangan, departemen, atau pengguna tersebut.
409 Sudah menjadi anggota tim, undangan tertunda sudah ada, atau departemen dengan nama tersebut sudah ada.
429 Kursi tim penuh, batas 20 undangan per hari tercapai, atau Anda mencapai batas kecepatan API.
504 Undangan yang Anda coba terima telah kedaluwarsa.

Kode bersama yang dapat dikembalikan oleh setiap endpoint — 429 (batas kecepatan) dan 500 — tercantum dengan panduan percobaan ulang di Kesalahan & Penomoran Halaman.


Terkait

  • Manajemen Tim — fitur yang sama di dasbor, dengan tangkapan layar.
  • Autentikasi — cara mengirim token ID Firebase alih-alih kunci API.
  • API Kontak — kontak yang menjadi batasan visibilitas anggota.