Mengirim aktivitas ke bot di Direct Line API 3.0
Menggunakan protokol Direct Line 3.0, klien dan bot dapat bertukar beberapa jenis aktivitas yang berbeda, termasuk aktivitas pesan , aktivitas pengetikan , dan aktivitas kustom yang didukung bot. Klien dapat mengirim satu aktivitas per permintaan.
Mengirim aktivitas
Untuk mengirim aktivitas ke bot, klien harus membuat objek Aktivitas untuk menentukan aktivitas dan kemudian mengeluarkan POST permintaan ke https://directline.botframework.com/v3/directline/conversations/{conversationId}/activities, menentukan objek Aktivitas dalam isi permintaan.
Cuplikan berikut memberikan contoh permintaan dan respons Aktivitas Kirim.
Minta
POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: application/json
[other headers]
{
"locale": "en-EN",
"type": "message",
"from": {
"id": "user1"
},
"text": "hello"
}
Respons
Ketika aktivitas dikirimkan ke bot, layanan merespons dengan kode status HTTP yang mencerminkan kode status bot. Jika bot menghasilkan kesalahan, respons HTTP 502 ("Gateway Buruk") dikembalikan ke klien sebagai respons terhadap permintaan Aktivitas Kirim.
Catatan
Ini dapat disebabkan oleh fakta bahwa token yang benar tidak digunakan. Hanya token yang diterima terhadap percakapan awal yang dapat digunakan untuk mengirim aktivitas.
Jika POST berhasil, respons berisi payload JSON yang menentukan ID Aktivitas yang dikirim ke bot.
HTTP/1.1 200 OK
[other headers]
{
"id": "0001"
}
Total waktu untuk permintaan/respons Aktivitas Kirim
Total waktu untuk MEMPOSTING pesan ke percakapan Direct Line adalah jumlah dari yang berikut ini:
- Waktu transit untuk permintaan HTTP untuk melakukan perjalanan dari klien ke layanan Direct Line
- Waktu pemrosesan internal dalam Direct Line (biasanya kurang dari 120ms)
- Waktu transit dari layanan Direct Line ke bot
- Waktu pemrosesan dalam bot
- Waktu transit untuk respons HTTP untuk melakukan perjalanan kembali ke klien
Mengirim lampiran ke bot
Dalam beberapa situasi, klien mungkin perlu mengirim lampiran ke bot seperti gambar atau dokumen. Klien dapat mengirim lampiran ke bot baik dengan menentukan URL lampiran dalam objek Aktivitas yang dikirimnya menggunakan POST /v3/directline/conversations/{conversationId}/activities atau dengan mengunggah lampiran menggunakan POST /v3/directline/conversations/{conversationId}/upload.
Kirim lampiran menurut URL
Untuk mengirim satu atau beberapa lampiran sebagai bagian dari objek Aktivitas menggunakan POST /v3/directline/conversations/{conversationId}/activities, cukup sertakan satu atau beberapa objek Lampiran dalam objek Aktivitas dan atur contentUrl properti dari setiap objek Lampiran untuk menentukan HTTP, HTTPS, atau data URI lampiran.
Mengirim lampiran dengan mengunggah
Seringkali, klien mungkin memiliki gambar atau dokumen pada perangkat yang ingin dikirim ke bot, tetapi tidak ada URL yang sesuai dengan file tersebut. Dalam situasi ini, klien dapat mengeluarkan POST /v3/directline/conversations/{conversationId}/upload permintaan untuk mengirim lampiran ke bot dengan mengunggah. Format dan konten permintaan akan bergantung pada apakah klien mengirim satu lampiran atau mengirim beberapa lampiran.
Mengirim lampiran tunggal dengan mengunggah
Untuk mengirim lampiran tunggal dengan mengunggah, terbitkan permintaan ini:
POST https://directline.botframework.com/v3/directline/conversations/{conversationId}/upload?userId={userId}
Authorization: Bearer SECRET_OR_TOKEN
Content-Type: TYPE_OF_ATTACHMENT
Content-Disposition: ATTACHMENT_INFO
[other headers]
[file content]
Dalam permintaan URI ini, ganti {conversationId} dengan ID percakapan dan {userId} dengan ID pengguna yang mengirim pesan. Parameter userId diperlukan. Di header permintaan, atur Content-Type untuk menentukan jenis lampiran dan atur Content-Disposition untuk menentukan nama file lampiran.
Cuplikan berikut memberikan contoh permintaan dan respons Kirim (tunggal) Lampiran.
Minta
POST https://directline.botframework.com/v3/directline/conversations/abc123/upload?userId=user1
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: image/jpeg
Content-Disposition: name="file"; filename="badjokeeel.jpg"
[other headers]
[JPEG content]
Respons
Jika permintaan berhasil, pesan Aktivitas dikirim ke bot saat unggahan selesai dan respons yang diterima klien akan berisi ID Aktivitas yang dikirim.
HTTP/1.1 200 OK
[other headers]
{
"id": "0003"
}
Mengirim beberapa lampiran dengan mengunggah
Untuk mengirim beberapa lampiran dengan mengunggah, POST permintaan multipisah ke /v3/directline/conversations/{conversationId}/upload titik akhir. Atur Content-Type header permintaan ke multipart/form-data dan sertakan Content-Type header dan Content-Disposition header untuk setiap bagian untuk menentukan jenis dan nama file setiap lampiran. Dalam permintaan URI, atur userId parameter ke ID pengguna yang mengirim pesan.
Anda dapat menyertakan Activity objek dalam permintaan dengan menambahkan bagian yang menentukan Content-Type nilai application/vnd.microsoft.activityheader . Jika permintaan menyertakan Aktivitas, lampiran yang ditentukan oleh bagian lain dari payload ditambahkan sebagai lampiran ke Aktivitas tersebut sebelum dikirim. Jika permintaan tidak menyertakan Aktivitas, Aktivitas kosong dibuat untuk berfungsi sebagai kontainer tempat lampiran yang ditentukan dikirim.
Cuplikan berikut memberikan contoh permintaan dan respons Kirim (beberapa) Lampiran. Dalam contoh ini, permintaan mengirim pesan yang berisi beberapa teks dan lampiran gambar tunggal. Bagian tambahan dapat ditambahkan ke permintaan untuk menyertakan beberapa lampiran dalam pesan ini.
Minta
POST https://directline.botframework.com/v3/directline/conversations/abc123/upload?userId=user1
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: multipart/form-data; boundary=----DD4E5147-E865-4652-B662-F223701A8A89
[other headers]
----DD4E5147-E865-4652-B662-F223701A8A89
Content-Type: image/jpeg
Content-Disposition: form-data; name="file"; filename="badjokeeel.jpg"
[other headers]
[JPEG content]
----DD4E5147-E865-4652-B662-F223701A8A89
Content-Type: application/vnd.microsoft.activity
[other headers]
{
"type": "message",
"from": {
"id": "user1"
},
"text": "Hey I just IM'd you\n\nand this is crazy\n\nbut here's my webhook\n\nso POST me maybe"
}
----DD4E5147-E865-4652-B662-F223701A8A89
Respons
Jika permintaan berhasil, pesan Aktivitas dikirim ke bot saat unggahan selesai dan respons yang diterima klien akan berisi ID Aktivitas yang dikirim.
HTTP/1.1 200 OK
[other headers]
{
"id": "0004"
}