Referensi API untuk layanan bot Framework Koneksi or
Catatan
REST API tidak setara dengan SDK. REST API disediakan untuk memungkinkan komunikasi REST standar, namun metode yang disukai untuk berinteraksi dengan Bot Framework adalah SDK.
Dalam Bot Framework, layanan Bot Koneksi or memungkinkan bot Anda untuk bertukar pesan dengan pengguna di saluran yang dikonfigurasi di Bot Framework Portal. Layanan ini menggunakan REST dan JSON standar industri melalui HTTPS.
URI Dasar
Saat pengguna mengirim pesan ke bot Anda, permintaan masuk berisi objek Aktivitas dengan serviceUrl
properti yang menentukan titik akhir tempat bot Anda harus mengirim responsnya. Untuk mengakses layanan Bot Koneksi or, gunakan serviceUrl
nilai sebagai URI dasar untuk permintaan API.
Saat Anda belum memiliki URL layanan untuk saluran, gunakan https://smba.trafficmanager.net/teams/
sebagai URL layanan. Untuk informasi selengkapnya, lihat cara membuat percakapan dan pesan proaktif di Teams.
Misalnya, asumsikan bahwa bot Anda menerima aktivitas berikut saat pengguna mengirim pesan ke bot.
{
"type": "message",
"id": "bf3cc9a2f5de...",
"timestamp": "2016-10-19T20:17:52.2891902Z",
"serviceUrl": "https://smba.trafficmanager.net/teams/",
"channelId": "channel's name/id",
"from": {
"id": "1234abcd",
"name": "user's name"
},
"conversation": {
"id": "abcd1234",
"name": "conversation's name"
},
"recipient": {
"id": "12345678",
"name": "bot's name"
},
"text": "Haircut on Saturday"
}
Properti serviceUrl
dalam pesan pengguna menunjukkan bahwa bot harus mengirim responsnya ke titik https://smba.trafficmanager.net/teams/
akhir . URL layanan akan menjadi URI dasar untuk setiap permintaan berikutnya yang masalah bot dalam konteks percakapan ini. Jika bot Anda perlu mengirim pesan proaktif kepada pengguna, pastikan untuk menyimpan nilai serviceUrl
.
Contoh berikut menunjukkan permintaan bahwa bot bermasalah untuk merespons pesan pengguna.
POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/bf3cc9a2f5de...
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json
{
"type": "message",
"from": {
"id": "12345678",
"name": "bot's name"
},
"conversation": {
"id": "abcd1234",
"name": "conversation's name"
},
"recipient": {
"id": "1234abcd",
"name": "user's name"
},
"text": "I have several times available on Saturday!",
"replyToId": "bf3cc9a2f5de..."
}
Header
Header permintaan
Selain header permintaan HTTP standar, setiap permintaan API yang Anda terbitkan harus menyertakan Authorization
header yang menentukan token akses untuk mengautentikasi bot Anda. Tentukan Authorization
header menggunakan format ini:
Authorization: Bearer ACCESS_TOKEN
Untuk detail tentang cara mendapatkan token akses untuk bot Anda, lihat Mengautentikasi permintaan dari bot Anda ke layanan Bot Koneksi or.
Header respons
Selain header respons HTTP standar, setiap respons akan berisi X-Correlating-OperationId
header. Nilai header ini adalah ID yang sesuai dengan entri log Bot Framework, yang berisi detail tentang permintaan. Saat Anda menerima respons kesalahan, Anda harus mengambil nilai header ini. Jika Anda tidak dapat menyelesaikan masalah secara independen, sertakan nilai ini dalam informasi yang Anda berikan kepada tim Dukungan saat melaporkan masalah.
Kode status HTTP
Kode status HTTP yang dikembalikan dengan setiap respons menunjukkan hasil permintaan yang sesuai.
Catatan
Tabel berikut menjelaskan kode status HTTP yang paling umum. Beberapa kesalahan dihasilkan oleh saluran. Untuk informasi selengkapnya, Anda mungkin perlu membaca dokumentasi pengembang saluran.
Kode status HTTP | Makna |
---|---|
200 | Permintaan berhasil. |
201 | Permintaan berhasil. |
202 | Permintaan diterima untuk diproses. |
204 | Permintaan berhasil tetapi tidak ada konten yang dikembalikan. |
400 | Permintaan salah bentuk atau salah. |
401 | Bot belum diautentikasi. |
403 | Bot tidak berwenang untuk melakukan operasi yang diminta. |
404 | Sumber daya yang diminta tidak ditemukan. |
405 | Saluran tidak mendukung operasi yang diminta. |
500 | Terjadi kesalahan server internal. |
503 | Layanan tidak tersedia untuk sementara. |
Kesalahan
Setiap respons yang menentukan kode status HTTP dalam rentang 4xx atau rentang 5xx akan menyertakan objek ErrorResponse dalam isi respons yang memberikan informasi tentang kesalahan. Jika Anda menerima respons kesalahan dalam rentang 4xx, periksa objek ErrorResponse untuk mengidentifikasi penyebab kesalahan dan mengatasi masalah Anda sebelum mengirimkan ulang permintaan.
Operasi percakapan
Gunakan operasi ini untuk membuat percakapan, mengirim pesan (aktivitas), dan mengelola konten percakapan.
Penting
Tidak semua saluran mendukung semua titik akhir. Namun, semua saluran harus mendukung balasan ke titik akhir aktivitas .
Misalnya, hanya Direct Line dan Web Chat yang mendukung titik akhir dapatkan percakapan .
Operasi | Deskripsi |
---|---|
Buat Percakapan | Membuat percakapan baru. |
Aktivitas penghapusan | Menghapus aktivitas yang ada. |
Menghapus anggota percakapan | Menghapus anggota dari percakapan. |
Mendapatkan anggota aktivitas | Mendapatkan anggota aktivitas yang ditentukan dalam percakapan yang ditentukan. |
Dapatkan anggota percakapan | Mendapatkan detail tentang anggota percakapan. |
Mendapatkan anggota percakapan | Mendapatkan anggota percakapan yang ditentukan. |
Mendapatkan anggota halaman percakapan | Mendapatkan anggota percakapan yang ditentukan satu halaman pada satu waktu. |
Mendapatkan percakapan | Mendapatkan daftar percakapan yang telah diikuti bot. |
Balas ke aktivitas | Mengirim aktivitas (pesan) ke percakapan yang ditentukan, sebagai balasan ke aktivitas yang ditentukan. |
Kirim Riwayat Percakapan | Mengunggah transkrip aktivitas sebelumnya ke percakapan. |
Kirim ke percakapan | Mengirim aktivitas (pesan) ke akhir percakapan yang ditentukan. |
Perbarui aktivitas | Memperbarui aktivitas yang ada. |
Mengunggah lampiran ke saluran | Mengunggah lampiran langsung ke penyimpanan blob saluran. |
Membuat percakapan
Membuat percakapan baru.
POST /v3/conversations
Konten | Deskripsi |
---|---|
Badan permintaan | Objek ConversationParameters |
Kembali | Objek ConversationResourceResponse |
Aktivitas penghapusan
Beberapa saluran memungkinkan Anda menghapus aktivitas yang ada. Jika berhasil, operasi ini akan menghapus aktivitas yang ditentukan dari percakapan yang ditentukan.
DELETE /v3/conversations/{conversationId}/activities/{activityId}
Konten | Deskripsi |
---|---|
Badan permintaan | n/a |
Kembali | Kode Status HTTP yang menunjukkan hasil operasi. Tidak ada yang ditentukan dalam isi respons. |
Menghapus anggota percakapan
Menghapus anggota dari percakapan. Jika anggota tersebut adalah anggota terakhir percakapan, percakapan juga akan dihapus.
DELETE /v3/conversations/{conversationId}/members/{memberId}
Konten | Deskripsi |
---|---|
Badan permintaan | n/a |
Kembali | Kode Status HTTP yang menunjukkan hasil operasi. Tidak ada yang ditentukan dalam isi respons. |
Mendapatkan anggota aktivitas
Mendapatkan anggota aktivitas yang ditentukan dalam percakapan yang ditentukan.
GET /v3/conversations/{conversationId}/activities/{activityId}/members
Konten | Deskripsi |
---|---|
Badan permintaan | n/a |
Kembali | Array objek ChannelAccount |
Mendapatkan percakapan
Mendapatkan daftar percakapan yang telah diikuti bot.
GET /v3/conversations?continuationToken={continuationToken}
Konten | Deskripsi |
---|---|
Badan permintaan | n/a |
Kembali | Objek ConversationsResult |
Dapatkan anggota percakapan
Mendapatkan detail tentang anggota tertentu dari percakapan tertentu.
GET /v3/conversations/{conversationId}/members/{memberId}
Konten | Deskripsi |
---|---|
Badan permintaan | n/a |
Kembali | Objek ChannelAccount untuk anggota. |
Mendapatkan anggota percakapan
Mendapatkan anggota percakapan yang ditentukan.
GET /v3/conversations/{conversationId}/members
Konten | Deskripsi |
---|---|
Badan permintaan | n/a |
Kembali | Array objek ChannelAccount untuk anggota percakapan. |
Mendapatkan anggota halaman percakapan
Mendapatkan anggota percakapan yang ditentukan satu halaman pada satu waktu.
GET /v3/conversations/{conversationId}/pagedmembers?pageSize={pageSize}&continuationToken={continuationToken}
Konten | Deskripsi |
---|---|
Badan permintaan | n/a |
Kembali | Objek PagedMembersResult |
Balas ke aktivitas
Mengirim aktivitas (pesan) ke percakapan yang ditentukan, sebagai balasan ke aktivitas yang ditentukan. Aktivitas akan ditambahkan sebagai balasan ke aktivitas lain, jika saluran mendukungnya. Jika saluran tidak mendukung balasan berlapis, maka operasi ini berperilaku seperti Kirim ke Percakapan.
POST /v3/conversations/{conversationId}/activities/{activityId}
Konten | Deskripsi |
---|---|
Badan permintaan | Objek Aktivitas |
Kembali | Objek ResourceResponse |
Mengirim riwayat percakapan
Mengunggah transkrip aktivitas sebelumnya ke percakapan sehingga klien dapat merendernya.
POST /v3/conversations/{conversationId}/activities/history
Konten | Deskripsi |
---|---|
Badan permintaan | Objek Transkrip . |
Kembali | Objek ResourceResponse . |
Kirim ke percakapan
Mengirim aktivitas (pesan) ke percakapan yang ditentukan. Aktivitas akan ditambahkan ke akhir percakapan sesuai dengan tanda waktu atau semantik saluran. Untuk membalas pesan tertentu dalam percakapan, gunakan Balas ke Aktivitas sebagai gantinya.
POST /v3/conversations/{conversationId}/activities
Konten | Deskripsi |
---|---|
Badan permintaan | Objek Aktivitas |
Kembali | Objek ResourceResponse |
Perbarui aktivitas
Beberapa saluran memungkinkan Anda mengedit aktivitas yang ada untuk mencerminkan status baru percakapan bot. Misalnya, Anda dapat menghapus tombol dari pesan dalam percakapan setelah pengguna mengklik salah satu tombol. Jika berhasil, operasi ini memperbarui aktivitas yang ditentukan dalam percakapan yang ditentukan.
PUT /v3/conversations/{conversationId}/activities/{activityId}
Konten | Deskripsi |
---|---|
Badan permintaan | Objek Aktivitas |
Kembali | Objek ResourceResponse |
Mengunggah lampiran ke saluran
Mengunggah lampiran untuk percakapan yang ditentukan langsung ke penyimpanan blob saluran. Ini memungkinkan Anda menyimpan data di penyimpanan yang sesuai.
POST /v3/conversations/{conversationId}/attachments
Konten | Deskripsi |
---|---|
Badan permintaan | Objek AttachmentData . |
Kembali | Objek ResourceResponse . Properti id menentukan ID lampiran yang dapat digunakan dengan operasi Dapatkan informasi lampiran dan operasi Dapatkan lampiran . |
Operasi lampiran
Gunakan operasi ini untuk mengambil informasi tentang lampiran serta data biner untuk file itu sendiri.
Operasi | Deskripsi |
---|---|
Dapatkan Info Lampiran | Mendapatkan informasi tentang lampiran yang ditentukan, termasuk nama file, jenis file, dan tampilan yang tersedia (misalnya, asli atau gambar mini). |
Dapatkan Lampiran | Mendapatkan tampilan lampiran yang ditentukan sebagai konten biner. |
Mendapatkan informasi lampiran
Mendapatkan informasi tentang lampiran yang ditentukan, termasuk nama file, jenis, dan tampilan yang tersedia (misalnya, asli atau gambar mini).
GET /v3/attachments/{attachmentId}
Konten | Deskripsi |
---|---|
Badan permintaan | n/a |
Kembali | Objek AttachmentInfo |
Mendapatkan lampiran
Mendapatkan tampilan lampiran yang ditentukan sebagai konten biner.
GET /v3/attachments/{attachmentId}/views/{viewId}
Konten | Deskripsi |
---|---|
Badan permintaan | n/a |
Kembali | Konten biner yang mewakili tampilan lampiran yang ditentukan |
Operasi status (tidak digunakan lagi)
Layanan Microsoft Bot Framework State dihentikan per 30 Maret 2018. Sebelumnya, bot yang dibangun di Azure AI Bot Service atau Bot Builder SDK memiliki koneksi default ke layanan ini yang dihosting oleh Microsoft untuk menyimpan data status bot. Bot perlu diperbarui untuk menggunakan penyimpanan status mereka sendiri.
Operasi | Deskripsi |
---|---|
Set User Data |
Menyimpan data status untuk pengguna tertentu di saluran. |
Set Conversation Data |
Menyimpan data status untuk percakapan tertentu di saluran. |
Set Private Conversation Data |
Menyimpan data status untuk pengguna tertentu dalam konteks percakapan tertentu di saluran. |
Get User Data |
Mengambil data status yang sebelumnya telah disimpan untuk pengguna tertentu di semua percakapan di saluran. |
Get Conversation Data |
Mengambil data status yang sebelumnya telah disimpan untuk percakapan tertentu di saluran. |
Get Private Conversation Data |
Mengambil data status yang sebelumnya telah disimpan untuk pengguna tertentu dalam konteks percakapan tertentu di saluran. |
Delete State For User |
Menghapus data status yang sebelumnya telah disimpan untuk pengguna. |
Skema
Skema Bot Framework menentukan objek dan propertinya yang dapat digunakan bot Anda untuk berkomunikasi dengan pengguna.
Objek | Deskripsi |
---|---|
Objek aktivitas | Menentukan pesan yang ditukar antara bot dan pengguna. |
Objek Kartu Animasi | Menentukan kartu yang dapat memutar GIF animasi atau video pendek. |
Objek lampiran | Menentukan informasi tambahan untuk disertakan dalam pesan. Lampiran mungkin berupa file media (misalnya, audio, video, gambar, file) atau kartu kaya. |
Objek AttachmentData | Menjelaskan data lampiran. |
Objek AttachmentInfo | Menjelaskan lampiran. |
Objek AttachmentView | Menentukan objek yang mewakili tampilan yang tersedia untuk lampiran. |
Objek AudioCard | Menentukan kartu yang dapat memutar file audio. |
Objek CardAction | Menentukan tindakan yang akan dilakukan. |
Objek CardImage | Menentukan gambar yang akan ditampilkan pada kartu. |
Objek ChannelAccount | Menentukan bot atau akun pengguna di saluran. |
Objek ConversationAccount | Menentukan percakapan dalam saluran. |
Objek ConversationMembers | Menentukan anggota percakapan. |
Objek ConversationParameters | Menentukan parameter untuk membuat percakapan baru |
Objek ConversationReference | Menentukan titik tertentu dalam percakapan. |
Objek ConversationResourceResponse | Menentukan respons untuk Membuat Percakapan. |
Objek ConversationsResult | Menentukan hasil panggilan ke Dapatkan Percakapan. |
Objek entitas | Menentukan objek entitas. |
Objek kesalahan | Menentukan kesalahan. |
Objek ErrorResponse | Menentukan respons API HTTP. |
Objek fakta | Menentukan pasangan kunci-nilai yang berisi fakta. |
Objek GeoCoordinates | Menentukan lokasi geografis menggunakan koordinat World Geodetic System (WSG84). |
Objek HeroCard | Menentukan kartu dengan gambar besar, judul, teks, dan tombol tindakan. |
Objek InnerHttpError | Objek yang mewakili kesalahan HTTP dalam. |
Objek MediaEventValue | Parameter tambahan untuk peristiwa media. |
Objek MediaUrl | Menentukan URL ke sumber file media. |
Sebutkan objek | Menentukan pengguna atau bot yang disebutkan dalam percakapan. |
Objek MessageReaction | Mendefinisikan reaksi terhadap pesan. |
Objek PagedMembersResult | Halaman anggota yang dikembalikan oleh Dapatkan Anggota Halaman Percakapan. |
Tempatkan objek | Menentukan tempat yang disebutkan dalam percakapan. |
Objek Kartu Tanda Terima | Menentukan kartu yang berisi tanda terima untuk pembelian. |
Objek ReceiptItem | Menentukan item baris dalam tanda terima. |
Objek ResourceResponse | Menentukan sumber daya. |
Objek SemanticAction | Menentukan referensi ke tindakan terprogram. |
Objek SignInCard | Menentukan kartu yang memungkinkan pengguna masuk ke layanan. |
Objek SuggestedActions | Menentukan opsi tempat pengguna dapat memilih. |
Objek TextHighlight | Mengacu pada substring konten dalam bidang lain. |
Objek ThumbnailCard | Menentukan kartu dengan gambar mini, judul, teks, dan tombol tindakan. |
Objek ThumbnailUrl | Menentukan URL ke sumber gambar. |
Objek Transkrip | Kumpulan aktivitas yang akan diunggah menggunakan Riwayat Kirim Percakapan. |
Objek VideoCard | Menentukan kartu yang dapat memutar video. |
Objek aktivitas
Menentukan pesan yang ditukar antara bot dan pengguna.
Properti | Tipe | Deskripsi |
---|---|---|
action | String | Tindakan yang akan diterapkan atau yang diterapkan. Gunakan properti jenis untuk menentukan konteks tindakan. Misalnya, jika jenisnya adalah contactRelationUpdate, nilai properti tindakan akan ditambahkan jika pengguna menambahkan bot Anda ke daftar kontak mereka, atau menghapus jika mereka menghapus bot Anda dari daftar kontak mereka. |
attachmentLayout | String | Tata letak lampiran kartu kaya yang disertakan pesan. Salah satu nilai ini: carousel, list. Untuk informasi selengkapnya tentang lampiran kartu kaya, lihat Menambahkan lampiran kartu kaya ke pesan. |
Lampiran | Lampiran[] | Array objek Lampiran yang menentukan informasi tambahan untuk disertakan dalam pesan. Setiap lampiran mungkin berupa file (misalnya, audio, video, gambar) atau kartu kaya. |
callerId | String | String yang berisi IRI yang mengidentifikasi pemanggil bot. Bidang ini tidak dimaksudkan untuk ditransmisikan melalui kawat, tetapi sebaliknya diisi oleh bot dan klien berdasarkan data yang dapat diverifikasi secara kriptografis yang menegaskan identitas pemanggil (misalnya, token). |
channelData | Objek | Objek yang berisi konten khusus saluran. Beberapa saluran menyediakan fitur yang memerlukan informasi tambahan yang tidak dapat diwakili menggunakan skema lampiran. Untuk kasus tersebut, atur properti ini ke konten khusus saluran seperti yang didefinisikan dalam dokumentasi saluran. Untuk informasi selengkapnya, lihat Menerapkan fungsionalitas khusus saluran. |
channelId | String | ID yang secara unik mengidentifikasi saluran. Diatur oleh saluran. |
code | String | Kode yang menunjukkan mengapa percakapan telah berakhir. |
Percakapan | ConversationAccount | Objek ConversationAccount yang menentukan percakapan tempat aktivitas berada. |
deliveryMode | String | Petunjuk pengiriman untuk memberi sinyal ke jalur pengiriman alternatif penerima untuk aktivitas tersebut. Salah satu nilai ini: normal, pemberitahuan. |
Entitas | object[] | Array objek yang mewakili entitas yang disebutkan dalam pesan. Objek dalam array ini mungkin objek Schema.org apa pun. Misalnya, array dapat mencakup objek Sebutan yang mengidentifikasi seseorang yang disebutkan dalam percakapan dan Menempatkan objek yang mengidentifikasi tempat yang disebutkan dalam percakapan. |
Kadaluarsa | String | Waktu di mana aktivitas harus dianggap "kedaluwarsa" dan tidak boleh disajikan kepada penerima. |
dari | ChannelAccount | Objek ChannelAccount yang menentukan pengirim pesan. |
historyDisclosed | Boolean | Bendera yang menunjukkan apakah riwayat diungkapkan atau tidak. Nilai defaultnya adalah false. |
id | String | ID yang secara unik mengidentifikasi aktivitas di saluran. |
Penting | String | Menentukan pentingnya Aktivitas. Salah satu nilai ini: rendah, normal, tinggi. |
inputHint | String | Nilai yang menunjukkan apakah bot Anda menerima, mengharapkan, atau mengabaikan input pengguna setelah pesan dikirimkan ke klien. Salah satu nilai ini: acceptingInput, expectingInput, ignoringInput. |
Label | String | Label deskriptif untuk aktivitas. |
listenFor | Tali[] | Daftar frasa dan referensi yang harus didengarkan oleh sistem pendeta ucapan dan bahasa. |
lokal | String | Lokal bahasa yang harus digunakan untuk menampilkan teks dalam pesan, dalam format <language>-<country> . Saluran menggunakan properti ini untuk menunjukkan bahasa pengguna, sehingga bot Anda dapat menentukan string tampilan dalam bahasa tersebut. Nilai defaultnya adalah en-US. |
localTimestamp | String | Tanggal dan waktu pesan dikirim di zona waktu lokal, dinyatakan dalam format ISO-8601 . |
localTimezone | String | Berisi nama zona waktu lokal pesan, yang dinyatakan dalam format database Zona Waktu IANA. Misalnya, Amerika/Los_Angeles. |
anggotaTambahkan | ChannelAccount[] | Array objek ChannelAccount yang mewakili daftar pengguna yang bergabung dalam percakapan. Sajikan hanya jika jenis aktivitas adalah "conversationUpdate" dan pengguna bergabung dalam percakapan. |
membersRemoved | ChannelAccount[] | Array objek ChannelAccount yang mewakili daftar pengguna yang meninggalkan percakapan. Sajikan hanya jika jenis aktivitas adalah "conversationUpdate" dan pengguna meninggalkan percakapan. |
nama | String | Nama operasi yang akan dipanggil atau nama peristiwa. |
reactionsAdded | MessageReaction[] | Kumpulan reaksi ditambahkan ke percakapan. |
reactionsRemoved | MessageReaction[] | Kumpulan reaksi dihapus dari percakapan. |
Penerima | ChannelAccount | Objek ChannelAccount yang menentukan penerima pesan. |
relatesTo | ConversationReference | Objek ConversationReference yang menentukan titik tertentu dalam percakapan. |
replyToId | String | ID pesan tempat pesan ini membalas. Untuk membalas pesan yang dikirim pengguna, atur properti ini ke ID pesan pengguna. Tidak semua saluran mendukung balasan berulir. Dalam kasus ini, saluran akan mengabaikan properti ini dan menggunakan semantik yang diurutkan waktu (tanda waktu) untuk menambahkan pesan ke percakapan. |
semantikAction | SemantikAction | Objek SemanticAction yang mewakili referensi ke tindakan terprogram. |
serviceUrl | String | URL yang menentukan titik akhir layanan saluran. Diatur oleh saluran. |
Berbicara | String | Teks yang akan diucapkan oleh bot Anda di saluran yang mendukung ucapan. Untuk mengontrol berbagai karakteristik ucapan bot Anda seperti suara, laju, volume, pengucapan, dan nada, tentukan properti ini dalam format Speech Synthesis Markup Language (SSML). |
suggestedActions | SuggestedActions | Objek SuggestedActions yang menentukan opsi tempat pengguna dapat memilih. |
ringkasan | String | Ringkasan informasi yang dimuat pesan. Misalnya, untuk pesan yang dikirim di saluran email, properti ini dapat menentukan 50 karakter pertama pesan email. |
text | String | Teks pesan yang dikirim dari pengguna ke bot atau bot ke pengguna. Lihat dokumentasi saluran untuk batas yang diberlakukan pada konten properti ini. |
textFormat | String | Format teks pesan. Salah satu nilai ini: markdown, polos, xml. Untuk detail tentang format teks, lihat Membuat pesan. |
textHighlights | TextHighlight[] | Kumpulan fragmen teks yang akan disorot saat aktivitas berisi nilai replyToId . |
timestamp | String | Tanggal dan waktu pesan dikirim di zona waktu UTC, yang dinyatakan dalam format ISO-8601 . |
topicName | String | Topik percakapan tempat aktivitas berada. |
jenis | String | Jenis aktivitas. Salah satu nilai ini: pesan, contactRelationUpdate, conversationUpdate, typing, endOfConversation, event, invoke, deleteUserData, messageUpdate, messageDelete, installationUpdate, messageReaction, suggestion, trace, handoff. Untuk detail tentang jenis aktivitas, lihat Gambaran umum aktivitas. |
value | Objek | Nilai terbuka. |
valueType | String | Jenis objek nilai aktivitas. |
Objek Kartu Animasi
Menentukan kartu yang dapat memutar GIF animasi atau video pendek.
Properti | Tipe | Deskripsi |
---|---|---|
Aspek | Boolean | Rasio aspek thumbnail/tempat penampung media. Nilai yang diizinkan adalah "16:9" dan "4:3". |
autoloop | Boolean | Bendera yang menunjukkan apakah akan memutar ulang daftar GIF animasi saat yang terakhir berakhir. Atur properti ini ke true untuk memutar ulang animasi secara otomatis; jika tidak, false. Nilai defaultnya adalah benar. |
Autostart | Boolean | Bendera yang menunjukkan apakah akan memutar animasi secara otomatis saat kartu ditampilkan. Atur properti ini ke true untuk memutar animasi secara otomatis; jika tidak, false. Nilai defaultnya adalah benar. |
Tombol | CardAction[] | Array objek CardAction yang memungkinkan pengguna melakukan satu atau beberapa tindakan. Saluran menentukan jumlah tombol yang mungkin Anda tentukan. |
durasi | String | Panjang konten media, dalam format durasi ISO 8601. |
gambar | ThumbnailUrl | Objek ThumbnailUrl yang menentukan gambar untuk ditampilkan pada kartu. |
media | MediaUrl[] | Array objek MediaUrl. Ketika bidang ini berisi lebih dari satu URL, setiap URL adalah format alternatif dari konten yang sama. |
Shareable | Boolean | Bendera yang menunjukkan apakah animasi dapat dibagikan dengan orang lain. Atur properti ini ke true jika animasi dapat dibagikan; jika tidak, salah. Nilai defaultnya adalah benar. |
Subjudul | String | Subjudul untuk ditampilkan di bawah judul kartu. |
text | String | Deskripsi atau perintah untuk ditampilkan di bawah judul atau subtitel kartu. |
title | String | Judul kartu. |
value | Objek | Parameter tambahan untuk kartu ini. |
Objek lampiran
Menentukan informasi tambahan untuk disertakan dalam pesan. Lampiran mungkin berupa file (seperti gambar, audio, atau video) atau kartu kaya.
Properti | Tipe | Deskripsi |
---|---|---|
Konten | Objek | Konten lampiran. Jika lampiran adalah kartu kaya, atur properti ini ke objek kartu kaya. Properti ini dan properti contentUrl saling eksklusif. |
contentType | String | Jenis media konten dalam lampiran. Untuk file media, atur properti ini ke jenis media yang diketahui seperti gambar/png, audio/wav, dan video/mp4. Untuk kartu kaya, atur properti ini ke salah satu jenis khusus vendor ini:
|
contentUrl | String | URL untuk konten lampiran. Misalnya, jika lampiran adalah gambar, Anda dapat mengatur contentUrl ke URL yang mewakili lokasi gambar. Protokol yang didukung adalah: HTTP, HTTPS, File, dan Data. |
nama | String | Nama lampiran. |
thumbnailUrl | String | URL ke gambar mini yang dapat digunakan saluran jika mendukung penggunaan bentuk konten atau contentUrl alternatif yang lebih kecil. Misalnya, jika Anda mengatur contentType ke aplikasi/kata dan mengatur contentUrl ke lokasi dokumen Word, Anda mungkin menyertakan gambar mini yang mewakili dokumen. Saluran dapat menampilkan gambar mini alih-alih dokumen. Saat pengguna mengklik gambar, saluran akan membuka dokumen. |
Objek AttachmentData
Menjelaskan data lampiran.
Properti | Tipe | Deskripsi |
---|---|---|
nama | String | Nama lampiran. |
originalBase64 | String | Konten lampiran. |
thumbnailBase64 | String | Konten gambar mini lampiran. |
jenis | String | Jenis konten lampiran. |
Objek AttachmentInfo
Metadata untuk lampiran.
Properti | Tipe | Deskripsi |
---|---|---|
nama | String | Nama lampiran. |
jenis | String | Jenis konten lampiran. |
tampilan | AttachmentView[] | Array objek AttachmentView yang mewakili tampilan yang tersedia untuk lampiran. |
Objek AttachmentView
Menentukan objek yang mewakili tampilan yang tersedia untuk lampiran.
Properti | Tipe | Deskripsi |
---|---|---|
ukuran | Angka | Ukuran file. |
viewId | String | Lihat ID. |
Objek AudioCard
Menentukan kartu yang dapat memutar file audio.
Properti | Tipe | Deskripsi |
---|---|---|
Aspek | String | Rasio aspek gambar mini yang ditentukan dalam properti gambar . Nilai yang valid adalah 16:9 dan 4:3. |
autoloop | Boolean | Bendera yang menunjukkan apakah akan memutar ulang daftar file audio saat yang terakhir berakhir. Atur properti ini ke true untuk memutar ulang file audio secara otomatis; jika tidak, false. Nilai defaultnya adalah benar. |
Autostart | Boolean | Bendera yang menunjukkan apakah akan memutar audio secara otomatis saat kartu ditampilkan. Atur properti ini ke true untuk memutar audio secara otomatis; jika tidak, false. Nilai defaultnya adalah benar. |
Tombol | CardAction[] | Array objek CardAction yang memungkinkan pengguna melakukan satu atau beberapa tindakan. Saluran menentukan jumlah tombol yang mungkin Anda tentukan. |
durasi | String | Panjang konten media, dalam format durasi ISO 8601. |
gambar | ThumbnailUrl | Objek ThumbnailUrl yang menentukan gambar untuk ditampilkan pada kartu. |
media | MediaUrl[] | Array objek MediaUrl. Ketika bidang ini berisi lebih dari satu URL, setiap URL adalah format alternatif dari konten yang sama. |
Shareable | Boolean | Bendera yang menunjukkan apakah file audio dapat dibagikan dengan orang lain. Atur properti ini ke true jika audio dapat dibagikan; jika tidak, salah. Nilai defaultnya adalah benar. |
Subjudul | String | Subjudul untuk ditampilkan di bawah judul kartu. |
text | String | Deskripsi atau perintah untuk ditampilkan di bawah judul atau subtitel kartu. |
title | String | Judul kartu. |
value | Objek | Parameter tambahan untuk kartu ini. |
Objek CardAction
Menentukan tindakan yang dapat diklik dengan tombol.
Properti | Tipe | Deskripsi |
---|---|---|
channelData | String | Data khusus saluran yang terkait dengan tindakan ini. |
displayText | String | Teks untuk ditampilkan di umpan obrolan jika tombol diklik. |
gambar | String | URL gambar yang akan muncul pada tombol, di samping label teks. |
text | String | Teks untuk tindakan. |
title | String | Deskripsi teks yang muncul di tombol . |
jenis | String | Jenis tindakan yang akan dilakukan. Untuk daftar nilai yang valid, lihat Menambahkan lampiran kartu kaya ke pesan. |
value | Objek | Parameter tambahan untuk tindakan. Perilaku properti ini akan bervariasi sesuai dengan jenis tindakan. Untuk informasi selengkapnya, lihat Menambahkan lampiran kartu kaya ke pesan. |
Objek CardImage
Menentukan gambar yang akan ditampilkan pada kartu.
Properti | Tipe | Deskripsi |
---|---|---|
Alt | String | Deskripsi gambar. Anda harus menyertakan deskripsi untuk mendukung aksesibilitas. |
Tekan | CardAction | Objek CardAction yang menentukan tindakan yang akan dilakukan jika pengguna mengetuk atau mengklik gambar. |
url | String | URL ke sumber gambar atau biner base64 gambar (misalnya, data:image/png;base64,iVBORw0KGgo... ). |
Objek ChannelAccount
Menentukan bot atau akun pengguna di saluran.
Properti | Tipe | Deskripsi |
---|---|---|
aadObjectId | String | ID objek akun ini dalam ID Microsoft Entra. |
id | String | ID unik untuk pengguna atau bot di saluran ini. |
nama | String | Nama bot atau pengguna yang mudah ditampilkan. |
role | String | Peran entitas di belakang akun. Baik pengguna atau bot. |
Objek ConversationAccount
Menentukan percakapan dalam saluran.
Properti | Tipe | Deskripsi |
---|---|---|
aadObjectId | String | ID objek akun ini dalam ID Microsoft Entra. |
conversationType | String | Menunjukkan jenis percakapan dalam saluran yang membedakan antara jenis percakapan (misalnya, grup atau pribadi). |
id | String | ID yang mengidentifikasi percakapan. ID unik per saluran. Jika saluran memulai percakapan, saluran akan menetapkan ID ini; jika tidak, bot mengatur properti ini ke ID yang didapatkannya kembali dalam respons saat memulai percakapan (lihat Buat Percakapan). |
isGroup | Boolean | Bendera untuk menunjukkan apakah percakapan berisi lebih dari dua peserta pada saat aktivitas dibuat. Atur ke true jika ini adalah percakapan grup; jika tidak, salah. Defaultnya adalah false. |
nama | String | Nama tampilan yang dapat digunakan untuk mengidentifikasi percakapan. |
role | String | Peran entitas di belakang akun. Baik pengguna atau bot. |
tenantId | String | ID penyewa percakapan ini. |
Objek ConversationMembers
Menentukan anggota percakapan.
Properti | Tipe | Deskripsi |
---|---|---|
id | String | ID percakapan. |
Anggota | ChannelAccount[] | Daftar anggota dalam percakapan ini. |
Objek ConversationParameters
Menentukan parameter untuk membuat percakapan baru.
Properti | Tipe | Deskripsi |
---|---|---|
Aktivitas | Tinggi | Pesan awal untuk dikirim ke percakapan saat dibuat. |
bot | ChannelAccount | Informasi akun saluran diperlukan untuk merutekan pesan ke bot. |
channelData | Objek | Payload khusus saluran untuk membuat percakapan. |
isGroup | Boolean | Menunjukkan apakah ini adalah percakapan grup. |
Anggota | ChannelAccount[] | Informasi akun saluran yang diperlukan untuk merutekan pesan ke setiap pengguna. |
tenantId | String | ID penyewa tempat percakapan harus dibuat. |
topicName | String | Topik percakapan. Properti ini hanya digunakan jika saluran mendukungnya. |
Objek ConversationReference
Menentukan titik tertentu dalam percakapan.
Properti | Tipe | Description |
---|---|---|
activityId | String | ID yang secara unik mengidentifikasi aktivitas yang dirujuk objek ini. |
bot | ChannelAccount | Objek ChannelAccount yang mengidentifikasi bot dalam percakapan yang direferensikan objek ini. |
channelId | String | ID yang secara unik mengidentifikasi saluran dalam percakapan yang dirujuk objek ini. |
Percakapan | ConversationAccount | Objek ConversationAccount yang menentukan percakapan yang direferensikan objek ini. |
serviceUrl | String | URL yang menentukan titik akhir layanan saluran dalam percakapan yang dirujuk objek ini. |
pengguna | ChannelAccount | Objek ChannelAccount yang mengidentifikasi pengguna dalam percakapan yang direferensikan objek ini. |
Objek ConversationResourceResponse
Menentukan respons untuk Membuat Percakapan.
Properti | Tipe | Description |
---|---|---|
activityId | String | ID aktivitas, jika dikirim. |
id | String | ID sumber daya. |
serviceUrl | String | Titik akhir layanan tempat operasi mengenai percakapan dapat dilakukan. |
Objek ConversationsResult
Menentukan hasil Dapatkan Percakapan.
Properti | Tipe | Deskripsi |
---|---|---|
Percakapan | ConversationMembers[] | Anggota di setiap percakapan. |
continuationToken | String | Token kelanjutan yang dapat digunakan dalam panggilan berikutnya ke Dapatkan Percakapan. |
Objek entitas
Objek metadata yang berkaitan dengan aktivitas.
Properti | Tipe | Deskripsi |
---|---|---|
jenis | String | Jenis entitas ini (RFC 3987 IRI). |
Objek kesalahan
Objek yang mewakili informasi kesalahan.
Properti | Tipe | Deskripsi |
---|---|---|
code | String | Kode Kesalahan. |
innerHttpError | InnerHttpError | Objek yang mewakili kesalahan HTTP dalam. |
message | String | Deskripsi kesalahan. |
Objek ErrorResponse
Menentukan respons API HTTP.
Properti | Tipe | Deskripsi |
---|---|---|
kesalahan | Kesalahan | Objek Kesalahan yang berisi informasi tentang kesalahan. |
Objek fakta
Menentukan pasangan kunci-nilai yang berisi fakta.
Properti | Tipe | Deskripsi |
---|---|---|
kunci | String | Nama fakta. Misalnya, Check-in. Kunci digunakan sebagai label saat menampilkan nilai fakta. |
value | String | Nilai faktanya. Misalnya, 10 Oktober 2016. |
Objek GeoCoordinates
Menentukan lokasi geografis menggunakan koordinat World Geodetic System (WSG84).
Properti | Tipe | Deskripsi |
---|---|---|
Elevasi | Angka | Elevasi lokasi. |
Latitude | Angka | Garis lintang lokasi. |
Bujur | Angka | Garis bujur lokasi. |
nama | String | Nama lokasi. |
jenis | String | Tipe objek ini. Selalu atur ke GeoCoordinates. |
Objek HeroCard
Menentukan kartu dengan gambar besar, judul, teks, dan tombol tindakan.
Properti | Tipe | Deskripsi |
---|---|---|
Tombol | CardAction[] | Array objek CardAction yang memungkinkan pengguna melakukan satu atau beberapa tindakan. Saluran menentukan jumlah tombol yang mungkin Anda tentukan. |
gambar | CardImage[] | Array objek CardImage yang menentukan gambar yang akan ditampilkan pada kartu. Kartu Hero hanya berisi satu gambar. |
Subjudul | String | Subjudul untuk ditampilkan di bawah judul kartu. |
Tekan | CardAction | Objek CardAction yang menentukan tindakan yang akan dilakukan jika pengguna mengetuk atau mengklik kartu. Tindakan ini bisa sama dengan salah satu tombol atau tindakan yang berbeda. |
text | String | Deskripsi atau perintah untuk ditampilkan di bawah judul atau subtitel kartu. |
title | String | Judul kartu. |
Objek InnerHttpError
Objek yang mewakili kesalahan HTTP dalam.
Properti | Tipe | Deskripsi |
---|---|---|
statusCode | Angka | Kode status HTTP dari permintaan yang gagal. |
body | Objek | Isi dari permintaan yang gagal. |
Objek MediaEventValue
Parameter tambahan untuk peristiwa media.
Properti | Tipe | Deskripsi |
---|---|---|
cardValue | Objek | Parameter panggilan balik yang ditentukan dalam bidang nilai kartu media yang berasal dari peristiwa ini. |
Objek MediaUrl
Menentukan URL ke sumber file media.
Properti | Tipe | Deskripsi |
---|---|---|
Profil | String | Petunjuk yang menjelaskan konten media. |
url | String | URL ke sumber file media. |
Sebutkan objek
Menentukan pengguna atau bot yang disebutkan dalam percakapan.
Properti | Tipe | Deskripsi |
---|---|---|
Disebutkan | ChannelAccount | Objek ChannelAccount yang menentukan pengguna atau bot yang disebutkan. Beberapa saluran, seperti Slack, menetapkan nama per percakapan, sehingga ada kemungkinan nama yang disebutkan bot Anda (di properti penerima pesan) mungkin berbeda dari handel yang Anda tentukan saat mendaftarkan bot Anda. Namun, ID akun untuk keduanya akan sama. |
text | String | Pengguna atau bot seperti yang disebutkan dalam percakapan. Misalnya, jika pesan "@ColorBot memilih saya warna baru," properti ini akan diatur ke @ColorBot. Tidak semua saluran menyetel properti ini. |
jenis | String | Tipe objek ini. Selalu atur ke Sebutkan. |
Objek MessageReaction
Mendefinisikan reaksi terhadap pesan.
Properti | Tipe | Deskripsi |
---|---|---|
jenis | String | Jenis reaksi. Baik suka atau plusOne. |
Objek PagedMembersResult
Halaman anggota yang dikembalikan oleh Dapatkan Anggota Halaman Percakapan.
Properti | Tipe | Deskripsi |
---|---|---|
continuationToken | String | Token kelanjutan yang dapat digunakan dalam panggilan berikutnya ke Dapatkan Anggota Halaman Percakapan. |
Anggota | ChannelAccount[] | Array anggota percakapan. |
Tempatkan objek
Menentukan tempat yang disebutkan dalam percakapan.
Properti | Tipe | Deskripsi |
---|---|---|
alamat | Objek | Alamat tempat. Properti ini bisa berupa string atau objek kompleks jenis PostalAddress. |
Geo | GeoCoordinates | Objek GeoCoordinates yang menentukan koordinat geografis tempat tersebut. |
hasMap | Objek | Petakan ke tempat itu. Properti ini bisa berupa string (URL) atau objek kompleks dari jenis Peta. |
nama | String | Nama tempat. |
jenis | String | Tipe objek ini. Selalu atur ke Tempat. |
Objek Kartu Tanda Terima
Menentukan kartu yang berisi tanda terima untuk pembelian.
Properti | Tipe | Deskripsi |
---|---|---|
Tombol | CardAction[] | Array objek CardAction yang memungkinkan pengguna melakukan satu atau beberapa tindakan. Saluran menentukan jumlah tombol yang mungkin Anda tentukan. |
Fakta | Fakta[] | Array objek Fakta yang menentukan informasi tentang pembelian. Misalnya, daftar fakta untuk tanda terima menginap hotel mungkin termasuk tanggal check-in dan tanggal check-out. Saluran menentukan jumlah fakta yang dapat Anda tentukan. |
items | ReceiptItem[] | Array objek ReceiptItem yang menentukan item yang dibeli |
Tekan | CardAction | Objek CardAction yang menentukan tindakan yang akan dilakukan jika pengguna mengetuk atau mengklik kartu. Tindakan ini bisa sama dengan salah satu tombol atau tindakan yang berbeda. |
Pajak | String | String berformat mata uang yang menentukan jumlah pajak yang diterapkan pada pembelian. |
title | String | Judul ditampilkan di bagian atas tanda terima. |
total | String | String berformat mata uang yang menentukan total harga pembelian, termasuk semua pajak yang berlaku. |
Ppn | String | String berformat mata uang yang menentukan jumlah pajak pertambahan nilai (PPN) yang diterapkan pada harga pembelian. |
Objek ReceiptItem
Menentukan item baris dalam tanda terima.
Properti | Tipe | Deskripsi |
---|---|---|
gambar | CardImage | Objek CardImage yang menentukan gambar mini untuk ditampilkan di samping item baris. |
price | String | String berformat mata uang yang menentukan harga total semua unit yang dibeli. |
Kuantitas | String | String numerik yang menentukan jumlah unit yang dibeli. |
Subjudul | String | Subjudul yang akan ditampilkan di bawah judul item baris. |
Tekan | CardAction | Objek CardAction yang menentukan tindakan yang akan dilakukan jika pengguna mengetuk atau mengklik item baris. |
text | String | Deskripsi item baris. |
title | String | Judul item baris. |
Objek ResourceResponse
Menentukan respons yang berisi ID sumber daya.
Properti | Tipe | Deskripsi |
---|---|---|
id | String | ID yang secara unik mengidentifikasi sumber daya. |
Objek SemanticAction
Menentukan referensi ke tindakan terprogram.
Properti | Tipe | Deskripsi |
---|---|---|
Entitas | Objek | Objek tempat nilai setiap properti adalah objek Entitas . |
id | String | ID tindakan ini. |
state | String | Status tindakan ini. Nilai yang diizinkan: mulai, lanjutkan, selesai. |
Objek SignInCard
Menentukan kartu yang memungkinkan pengguna masuk ke layanan.
Properti | Tipe | Deskripsi |
---|---|---|
Tombol | CardAction[] | Array objek CardAction yang memungkinkan pengguna untuk masuk ke layanan. Saluran menentukan jumlah tombol yang mungkin Anda tentukan. |
text | String | Deskripsi atau permintaan untuk disertakan pada kartu masuk. |
Objek SuggestedActions
Menentukan opsi tempat pengguna dapat memilih.
Properti | Tipe | Deskripsi |
---|---|---|
actions | CardAction[] | Array objek CardAction yang menentukan tindakan yang disarankan. |
ke | Tali[] | Array string yang berisi ID penerima yang harus ditampilkan tindakan yang disarankan. |
Objek TextHighlight
Mengacu pada substring konten dalam bidang lain.
Properti | Tipe | Deskripsi |
---|---|---|
kemunculan | Angka | Kemunculan bidang teks dalam teks yang dirujuk, jika ada beberapa. |
text | String | Menentukan cuplikan teks yang akan disorot. |
Objek ThumbnailCard
Menentukan kartu dengan gambar mini, judul, teks, dan tombol tindakan.
Properti | Tipe | Deskripsi |
---|---|---|
Tombol | CardAction[] | Array objek CardAction yang memungkinkan pengguna melakukan satu atau beberapa tindakan. Saluran menentukan jumlah tombol yang mungkin Anda tentukan. |
gambar | CardImage[] | Array objek CardImage yang menentukan gambar mini untuk ditampilkan pada kartu. Saluran menentukan jumlah gambar mini yang dapat Anda tentukan. |
Subjudul | String | Subjudul untuk ditampilkan di bawah judul kartu. |
Tekan | CardAction | Objek CardAction yang menentukan tindakan yang akan dilakukan jika pengguna mengetuk atau mengklik kartu. Tindakan ini bisa sama dengan salah satu tombol atau tindakan yang berbeda. |
text | String | Deskripsi atau perintah untuk ditampilkan di bawah judul atau subtitel kartu. |
title | String | Judul kartu. |
Objek ThumbnailUrl
Menentukan URL ke sumber gambar.
Properti | Tipe | Deskripsi |
---|---|---|
Alt | String | Deskripsi gambar. Anda harus menyertakan deskripsi untuk mendukung aksesibilitas. |
url | String | URL ke sumber gambar atau biner base64 gambar (misalnya, data:image/png;base64,iVBORw0KGgo... ). |
Objek Transkrip
Kumpulan aktivitas yang akan diunggah menggunakan Riwayat Kirim Percakapan.
Properti | Tipe | Deskripsi |
---|---|---|
Kegiatan | array | Array objek Aktivitas . Mereka masing-masing harus memiliki ID dan tanda waktu yang unik. |
Objek VideoCard
Menentukan kartu yang dapat memutar video.
Properti | Tipe | Deskripsi |
---|---|---|
Aspek | String | Rasio aspek video. Baik 16:9 atau 4:3. |
autoloop | Boolean | Bendera yang menunjukkan apakah akan memutar ulang daftar video saat yang terakhir berakhir. Atur properti ini ke true untuk memutar ulang video secara otomatis; jika tidak, false. Nilai defaultnya adalah benar. |
Autostart | Boolean | Bendera yang menunjukkan apakah akan memutar video secara otomatis saat kartu ditampilkan. Atur properti ini ke true untuk memutar video secara otomatis; jika tidak, false. Nilai defaultnya adalah benar. |
Tombol | CardAction[] | Array objek CardAction yang memungkinkan pengguna melakukan satu atau beberapa tindakan. Saluran menentukan jumlah tombol yang mungkin Anda tentukan. |
durasi | String | Panjang konten media, dalam format durasi ISO 8601. |
gambar | ThumbnailUrl | Objek ThumbnailUrl yang menentukan gambar untuk ditampilkan pada kartu. |
media | MediaUrl[] | Array MediaUrl. Ketika bidang ini berisi lebih dari satu URL, setiap URL adalah format alternatif dari konten yang sama. |
Shareable | Boolean | Bendera yang menunjukkan apakah video dapat dibagikan dengan orang lain. Atur properti ini ke true jika video dapat dibagikan; jika tidak, salah. Nilai defaultnya adalah benar. |
Subjudul | String | Subjudul untuk ditampilkan di bawah judul kartu. |
text | String | Deskripsi atau perintah untuk ditampilkan di bawah judul atau subtitel kartu. |
title | String | Judul kartu. |
value | Objek | Parameter tambahan untuk kartu ini |