Kontak

Kontak adalah representasi pelanggan/lead di workspace Chatera. Setiap percakapan WhatsApp / IG / FB selalu terhubung ke satu kontak. API saat ini menyediakan dua endpoint untuk kontak: list dan create.

Update & delete belum tersedia

Endpoint PATCH /v1/contacts/{id} dan DELETE /v1/contacts/{id} belum tersedia di API publik. Untuk mengubah atau menghapus kontak, saat ini lakukan dari dashboard. Endpoint ini akan ditambahkan di iterasi berikutnya.

List kontak

GET /v1/contacts

Scope yang dibutuhkan: contacts:read

Query parameter

Parameter	Tipe	Default	Keterangan
`page`	number	`1`	Halaman yang diminta
`per_page`	number	`20` (maks `100`)	Jumlah kontak per halaman
`search`	string	—	Cari berdasarkan nama, nomor telepon, atau email

Contoh request

curl -X GET "https://api.chatera.id/v1/contacts?page=1&per_page=20&search=hafari" \
  -H "Authorization: Bearer chatera_sk_xxxxx"

Contoh response

{
  "success": true,
  "data": [
    {
      "id": "9b8c1234-e5f6-4789-90ab-cdef01234567",
      "phone": "+628123456789",
      "name": "Hafari",
      "email": "hafari@example.com",
      "tags": ["customer", "vip"],
      "custom_fields": {
        "company": "PT ABC"
      },
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-04-20T08:12:33Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "has_more": false
  }
}

Field response

Field	Tipe	Keterangan
`id`	string (UUID)	ID unik kontak
`phone`	string	Nomor telepon dalam format E.164 (dengan `+`)
`name`	string \| null	Nama lengkap
`email`	string \| null	Alamat email
`tags`	string[]	Label yang ditempelkan ke kontak
`custom_fields`	object	Atribut custom (key-value)
`created_at`	string (ISO 8601)	Waktu pembuatan
`updated_at`	string (ISO 8601)	Waktu update terakhir

Buat kontak

POST /v1/contacts

Scope yang dibutuhkan: contacts:write

Request body

Field	Wajib	Tipe	Keterangan
`phone`	✅	string	Format E.164 — `+628xxx` atau `628xxx`
`name`	—	string	Nama kontak
`email`	—	string	Alamat email valid
`tags`	—	string[]	Array label, mis. `["customer", "vip"]`
`custom_fields`	—	object	Pasangan key-value untuk atribut tambahan

Contoh request

curl -X POST "https://api.chatera.id/v1/contacts" \
  -H "Authorization: Bearer chatera_sk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "628123456789",
    "name": "Hafari",
    "email": "hafari@example.com",
    "tags": ["customer"],
    "custom_fields": {
      "company": "PT ABC",
      "tier": "gold"
    }
  }'

Contoh response sukses

{
  "success": true,
  "data": {
    "id": "9b8c1234-e5f6-4789-90ab-cdef01234567",
    "phone": "+628123456789",
    "name": "Hafari",
    "email": "hafari@example.com",
    "tags": ["customer"],
    "custom_fields": {
      "company": "PT ABC",
      "tier": "gold"
    },
    "created_at": "2026-04-27T11:20:00Z",
    "updated_at": "2026-04-27T11:20:00Z"
  }
}

Pesan error yang mungkin muncul

Kode	Penyebab	Solusi
`VALIDATION_INVALID_PHONE`	Format nomor salah	Pakai E.164: `628xxx` atau `+628xxx`
`VALIDATION_MISSING_FIELD`	Field `phone` kosong	Wajib isi `phone`
`RESOURCE_ALREADY_EXISTS`	Kontak dengan nomor ini sudah ada	Pakai endpoint list untuk dapatkan ID, lalu update via dashboard
`AUTH_INSUFFICIENT_SCOPE`	Key tidak punya `contacts:write`	Buat key baru dengan scope tersebut

Catatan tentang tag

Tag bersifat organisasi-level — semua agen di workspace melihat tag yang sama.
Tag baru otomatis dibuat saat kamu menyertakannya di body — tidak perlu pre-register.
Filter list kontak by tag belum tersedia di API. Sementara, filter di sisi client setelah fetch.

Custom fields

custom_fields menerima objek bebas key-value dengan tipe primitif (string, number, boolean). Contoh use case:

"custom_fields": {
  "customer_id": "CUST-2026-0042",
  "lifetime_value": 12500000,
  "is_subscriber": true,
  "last_purchase_at": "2026-04-15"
}

Custom fields dapat dipakai untuk:

Menyimpan reference ID dari sistem internal kamu.
Personalisasi pesan WhatsApp via merge tag (akan datang).
Filter di dashboard.

Kontak

On this page