Gunakan peristiwa websocket untuk mendapatkan pembaruan waktu nyata
Websockets menciptakan koneksi persisten antara klien dan server yang memungkinkan komunikasi dua arah. omnichannel mendukung koneksi websocket untuk mendapatkan pembaruan waktu nyata tentang peristiwa yang terjadi di platform. Setiap klien dapat terhubung ke URL websocket di omnichannel dan mengotorisasi diri mereka sendiri dengan memberikan token dan mulai menerima pembaruan. Panduan ini akan membantu Anda menyiapkan koneksi websocket dengan omnichannel dan mengintegrasikan event yang tersedia.
Catatan: Ini adalah fitur eksperimental. Dokumentasi dapat berubah pada setiap rilis, dan tidak ada jaminan kompatibilitas ke belakang. Pastikan Anda menggunakan versi terbaru dari implementasi.
Mengapa saya harus menggunakan koneksi websocket?
Misalkan Anda membangun klien untuk omnichannel. Misalnya, dalam SDK Klien Android atau iOS, di mana Anda perlu mendengarkan pesan terbaru untuk memperbarui UI tanpa memuat ulang atau ekstensi ke dasbor, jika Anda ingin meningkatkan produktivitas agen, Anda mungkin memerlukan data secara real-time.
Menyiapkan koneksi websocket dengan omnichannel
Untuk menyiapkan koneksi websocket dengan omnichannel, Anda perlu memulai koneksi dengan token pubsub autentikasi yang disediakan oleh omnichannel. URL untuk koneksi adalah wss://<your-installation-url>/cable. Contoh wss://app.omnichannel.com/cable.
Ada dua jenis token pub yang tersedia di omnichannel.
Token PubSub Pengguna: Token ini memiliki hak istimewa sebagai agen/admin dan akan menerima semua peristiwa yang didokumentasikan di bawah ini. Anda bisa mendapatkan token pubsub dengan memanggil API Profil.
Hubungi Token PubSub: Untuk setiap kontak, omnichannel akan menghasilkan token pubsub untuk setiap sesi yang mereka miliki. Anda dapat terhubung ke websocket menggunakan token ini untuk mendapatkan pembaruan dari sesi saat ini. Ketika Anda membuat kontak menggunakan API publik, Anda akan menerima pubsub_token di dalam payload. Token ini hanya memiliki akses ke peristiwa terkait sesi saat ini, Anda hanya akan menerima peristiwa conversation.created, conversation.status_changed, message.created, message.updated, conversation_typing_on, conversation_typing_off, dan presence.update.
Silakan lihat API Klien untuk membangun integrasi yang berhadapan langsung dengan pelanggan menggunakan omnichannel.
Catatan: Token ini dapat dirotasi secara teratur berdasarkan jenis instalasi Anda, pastikan Anda menggunakan token terbaru.
Hubungkan ke Websocket omnichannel
Anda perlu mengirimkan perintah “subscribe” untuk terhubung ke omnichannel. Perintah ini akan meminta token pubSub, accountId, dan userId (jika menggunakan token pengguna). Berikut ini adalah contoh bagaimana Anda dapat terhubung dengan omnichannel.
// Menambahkan metode pembantu untuk mengonversi JSON menjadi string
const stringify = (payload = {}) => JSON.stringify(payload);
const pubSubToken = "<contact/user-pub-sub-token>";
const accountId = "<your-account-id-in-integer>";
const userId = "<user-id-in-integer-if-using-user-token>";
const connection = new WebSocket(
"wss://<your-Omnichannel-installation-host-url>/cable"
);
connection.send(
stringify({
command: "subscribe",
identifier: stringify({
channel: "RoomChannel",
pubsub_token: pubSubToken,
account_id: accountId,
user_id: userId,
}),
})
);
// The expected string in connection.send is of the format:
// {"command":"subscribe","identifier":"{\"channel\":\"RoomChannel\",\"pubsub_token\":\"your-pubsub-token\",\"account_id\": account_id_integer,\"user_id\":user_id_integer }"}
Menerbitkan Kehadiran ke server websocket
Untuk menjaga agar pengguna Anda tetap online di Omnichannel, Anda dapat mengirimkan peristiwa pembaruan kehadiran ke Omnichannel setiap 30 detik. Tindakan ini akan menjaga status agen/kontak tetap online.
Memperbarui keberadaan pengguna agen/admin
Muatan yang harus dikirim ke server untuk memperbarui keberadaan agen/admin adalah sebagai berikut.
const userPayload = stringify({
command: "message",
identifier: stringify({
channel: "RoomChannel",
pubsub_token: "<user-pubsub-token>",
account_id: accountId,
user_id: userId,
}),
data: stringify({ action: "update_presence" }),
});
connection.send(userPayload);
// The expected string in connection.send is of the format:
// {"command":"message","identifier":"{\"channel\":\"RoomChannel\",\"pubsub_token\":\"your-pubsub-token\",\"account_id\": account_id_integer,\"user_id\":user_id_integer ","data":"{\"action\":\"update_presence\"}"}
Memperbarui keberadaan kontak
Muatan yang harus dikirim ke server untuk memperbarui keberadaan kontak adalah sebagai berikut.
const agentPayload = stringify({
command: "message",
identifier: stringify({
channel: "RoomChannel",
pubsub_token: "<user-pubsub-token>",
}),
data: stringify({ action: "update_presence" }),
});
connection.send(agentPayload);
// The expected string in connection.send is of the format:
// {"command":"message","identifier":"{\"channel\":\"RoomChannel\",\"pubsub_token\":\"your-pubsub-token\","data":"{\"action\":\"update_presence\"}"}
Muatan Soket Web
Objek
Sebuah peristiwa dapat berisi salah satu objek berikut sebagai muatan. Berbagai jenis objek yang didukung di Omnichannel adalah sebagai berikut.
Percakapan
Muatan berikut akan dikembalikan untuk percakapan.
{"additional_attributes": {"browser": {"device_name": "string","browser_name": "string","platform_name": "string","browser_version": "string","platform_version": "string"},"referer": "string","initiated_at": {"timestamp": "iso-datetime"}},"can_reply": "boolean","channel": "string","id": "integer","inbox_id": "integer","contact_inbox": {"id": "integer","contact_id": "integer","inbox_id": "integer","source_id": "string","created_at": "datetime","updated_at": "datetime","hmac_verified": "boolean"},"messages": ["Array of message objects"],"meta": {"sender": {// Contact Object},"assignee": {// User Object}},"status": "string","unread_count": "integer","agent_last_seen_at": "unix-timestamp","contact_last_seen_at": "unix-timestamp","timestamp": "unix-timestamp","account_id": "integer"}
Kontak
Muatan berikut ini akan dikembalikan untuk sebuah kontak.
{
"additional_attributes": "object",
"custom_attributes": "object",
"email": "string",
"id": "integer",
"identifier": "string or null",
"name": "string",
"phone_number": "string or null",
"thumbnail": "string"
}
Pengguna
Muatan berikut akan dikembalikan untuk agen/admin.
{
"id": "integer",
"name": "string",
"available_name": "string",
"avatar_url": "string",
"availability_status": "string",
"thumbnail": "string"
}
Pesan
{
"id": "integer",
"content": "string",
"account_id": "integer",
"inbox_id": "integer",
"message_type": "integer",
"created_at": "unix-timestamp",
"updated_at": "datetime",
"private": "boolean",
"status": "string",
"source_id": "string / null",
"content_type": "string",
"content_attributes": "object",
"sender_type": "string",
"sender_id": "integer",
"external_source_ids": "object",
"sender": {
"type": "string - contact/user"
// User or Contact Object
}
}
Pemberitahuan
Muatan berikut akan dikembalikan untuk pemberitahuan.
{
"id": "integer",
"notification_type": "string",
"primary_actor_type": "string",
"primary_actor_id": "integer",
"primary_actor": {
"can_reply": "boolean",
"channel": "string",
"id": "integer",
"inbox_id": "integer",
"meta": {
"assignee": {
"id": "integer",
"name": "string",
"available_name": "string",
"avatar_url": "string",
"type": "user",
"availability_status": "string",
"thumbnail": "string"
},
"hmac_verified": "boolean"
},
"agent_last_seen_at": "unix-timestamp",
"contact_last_seen_at": "unix-timestamp",
"timestamp": "unix-timestamp",
},
"read_at": "unix-timestamp",
"secondary_actor": "object/null",
"created_at":"unix-timestamp",
"account_id": "integer",
"push_message_title": "string"
}
Pengenal
Setiap peristiwa akan memiliki atribut pengenal/identifieryang memiliki format sebagai berikut.
{
"identifier": "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"token\",\"account_id\":id,\"user_id\":user_id}"
}
Pesan
Setiap acara akan memiliki pesan/message yang mengembalikan nama peristiwa serta data yang terkait dengannya. Untuk melihat daftar peristiwa, lihat dokumentasi di bawah ini.
Acara
conversation.created
Peristiwa ini dikirim ketika percakapan baru dibuat. Untuk langganan token pub kontak, token ini hanya mengirimkan peristiwa yang terkait dengan sesi yang dikaitkan dengan token pub.
Tersedia untuk: agen/admin, kontak
{
"message": {
"event": "conversation.created",
"data": {
// Conversation object will be available here
}
}
}
conversation.read
Peristiwa ini dikirim ke agen/admin yang mengakses kotak masuk ketika pesan dibaca oleh kontak.
Tersedia untuk: agen/admin
{
"message": {
"event": "conversation.read",
"data": {
// Conversation object will be available here
}
}
}
message.created
Peristiwa ini dikirim ke agen, admin/kontak ketika pesan baru dibuat dalam percakapan yang dapat mereka akses.
Tersedia untuk: agen/admin, kontak
{
"message": {
"event": "message.created",
"data": {
// Message object will be available here
}
}
}
message.updated
Peristiwa ini dikirim ke agen, admin/kontak ketika sebuah pesan diperbarui dalam percakapan yang dapat mereka akses.
Tersedia untuk: agen/admin, kontak
{
"message": {
"event": "message.updated",
"data": {
// Message object will be available here
}
}
}
percakapan.status_berubah
Peristiwa ini dikirim ke agen, admin/kontak ketika status percakapan diperbarui.
Tersedia untuk: agen/admin, kontak
{
"message": {
"event": "conversation.status_changed",
"data": {
// Conversation object will be available here
}
}
}
conversation.typing_on
Peristiwa ini dikirim ke agen, admin/kontak ketika kontak atau agen mulai mengetik tanggapan.
Tersedia untuk: agen/admin, kontak
{
"message": {
"event": "conversation.typing_on",
"data": {
"conversation": {
// Conversation object will be available here
},
"user": {
// Contact / Agent,Admin User object will be available here.
},
"is_private": "boolean", // Shows whether the agent is typing a private note or not.
"account_id": "integer"
}
}
}
percakapan.mengetik_off
Peristiwa ini dikirim ke agen, admin/kontak ketika kontak atau agen selesai mengetik tanggapan.
Tersedia untuk: agen/admin, kontak
{
"message": {
"event": "conversation.typing_off",
"data": {
"conversation": {
// Conversation object will be available here
},
"user": {
// Contact / User object will be available here.
},
"account_id": "integer"
}
}
}
assignee.changed
Peristiwa ini dikirim ke agen/admin yang memiliki akses ke kotak masuk ketika penugasan diubah.
Tersedia untuk: agen/admin
{
"message": {
"event": "assignee.changed",
"data": {
// Conversation object will be available here
}
}
}
team.changed
Peristiwa ini dikirim ke agen/admin yang memiliki akses ke kotak masuk ketika penugasan tim diubah.
Tersedia untuk: agen/admin
{
"message": {
"event": "team.changed",
"data": {
// Conversation object will be available here
}
}
}
percakapan.kontak_berubah
Peristiwa ini dikirim ke agen/admin ketika kontak digabungkan. Objek percakapan akan memiliki referensi kontak yang baru.
Tersedia untuk: agen/admin
{
"message": {
"event": "conversation.contact_changed",
"data": {
// Conversation object will be available here
}
}
}
contact.created
Peristiwa ini dikirim ke agen/admin ketika kontak dibuat.
Tersedia untuk: agen/admin
{
"message": {
"event": "contact.created",
"data": {
// Contact object will be available here
}
}
}
contact.updated
Peristiwa ini dikirim ke agen/admin ketika sebuah kontak diperbarui.
Tersedia untuk: agen/admin
{
"message": {
"event": "contact.updated",
"data": {
// Contact object will be available here
}
}
}
presence.update
Peristiwa ini akan tersedia untuk agen dan kontak, peristiwa ini akan mengembalikan status ketersediaan pengguna dalam sistem. Peristiwa kehadiran yang dikirimkan ke kontak tidak akan memiliki informasi tentang kontak lain.
Tersedia untuk: agen/admin
{
"message": {
"event": "presence.update",
"data": {
"account_id": "integer",
"users": {
"user-id": "string"
},
"contacts": {
"contact-id": "string"
}
}
}
}
notifikasi_dibuat
Tersedia untuk: agen/admin
{
"message": {
"event": "string",
"data": {
"notification":{
// Notification object will be available here
},
"unread_count": "integer",
"count": "integer",
}
}
}
