Bot Bağlayıcısı API'siyle ileti gönderme ve alma
Bot Bağlayıcısı hizmeti, botların Email, Slack ve daha fazlası gibi birden çok kanalda iletişim kurmasını sağlar. Etkinlikleri bottan kanala ve kanaldan bota geçirerek bot ve kullanıcı arasındaki iletişimi kolaylaştırır. Her etkinlik, iletiyi kimin oluşturduğu, iletinin bağlamı ve iletinin alıcısı hakkındaki bilgilerle birlikte iletiyi uygun hedefe yönlendirmek için kullanılan bilgileri içerir. Bu makalede, bot ile kanaldaki kullanıcı arasında ileti etkinlikleri alışverişi yapmak için Bot Bağlayıcısı hizmetinin nasıl kullanılacağı açıklanır.
İletiyi yanıtlama
Yanıt oluşturma
Kullanıcı botunuza bir ileti gönderdiğinde, botunuz iletiyi ileti türünde bir Etkinlik nesnesi olarak alır. Kullanıcının iletisine yanıt oluşturmak için yeni Activity bir nesne oluşturun ve şu özellikleri ayarlayarak başlayın:
| Özellik | Değer |
|---|---|
| konuşma | Bu özelliği, kullanıcının iletisindeki conversation özelliğinin içeriğine ayarlayın. |
| Kaynak | Bu özelliği, kullanıcının iletisindeki recipient özelliğinin içeriğine ayarlayın. |
| locale | Bu özelliği, belirtilmişse kullanıcının iletisindeki özelliğin içeriğine locale ayarlayın. |
| Alıcı | Bu özelliği, kullanıcının iletisindeki from özelliğinin içeriğine ayarlayın. |
| replyToId | Bu özelliği, kullanıcının iletisindeki id özelliğinin içeriğine ayarlayın. |
| tür | Bu özelliği ileti olarak ayarlayın. |
Ardından, kullanıcıyla iletişim kurmak istediğiniz bilgileri belirten özellikleri ayarlayın. Örneğin, özelliğini iletide görüntülenecek metni belirtecek şekilde ayarlayabilir text , speak özelliğini botunuz tarafından konuşulacak metni belirtecek şekilde ayarlayabilir ve özelliği, iletiye eklenecek medya eklerini veya zengin kartları belirtecek şekilde ayarlayabilirsiniz attachments . Yaygın olarak kullanılan ileti özellikleri hakkında ayrıntılı bilgi için bkz. İleti oluşturma.
Yanıtı gönderme
serviceUrl Botunuzun yanıtını vermek için kullanması gereken temel URI'yi belirlemek için gelen etkinlikteki özelliğini kullanın.
Yanıtı göndermek için şu isteği gönderin:
POST /v3/conversations/{conversationId}/activities/{activityId}
Bu istek URI'sinde {conversationId} öğesini (reply) Etkinliğinizdeki nesnenin id özelliğinin conversation değeriyle değiştirin ve {activityId} öğesini (reply) Etkinliğinizdeki özelliğin replyToId değeriyle değiştirin. İsteğin gövdesini, yanıtınızı temsil etmek için oluşturduğunuz Activity nesnesine ayarlayın.
Aşağıdaki örnekte, kullanıcının iletisine basit bir yalnızca metin yanıtı gönderen bir istek gösterilmektedir. Bu örnek istekte temel https://smba.trafficmanager.net/teams URI'yi temsil eder; bot sorunlarınızın farklı olabileceği isteklerin temel URI'sini temsil eder. Temel URI'yi ayarlama hakkında ayrıntılı bilgi için bkz. API Başvurusu.
POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/5d5cdc723
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"type": "message",
"from": {
"id": "12345678",
"name": "Pepper's News Feed"
},
"conversation": {
"id": "abcd1234",
"name": "Convo1"
},
"recipient": {
"id": "1234abcd",
"name": "SteveW"
},
"text": "My bot's reply",
"replyToId": "5d5cdc723"
}
(Yanıtsız) ileti gönderme
Botunuzun gönderdiği iletilerin çoğu, kullanıcıdan aldığı iletilere yanıt olarak yer alır. Ancak, botunuzun konuşmaya kullanıcıdan gelen herhangi bir iletiye doğrudan yanıt olmayan bir ileti göndermesi gereken zamanlar olabilir. Örneğin, botunuzun yeni bir konuşma konusu başlatması veya konuşmanın sonunda bir veda iletisi göndermesi gerekebilir.
Kullanıcıdan gelen herhangi bir iletiye doğrudan yanıt olmayan bir konuşmaya ileti göndermek için şu isteği gönderin:
POST /v3/conversations/{conversationId}/activities
Bu istek URI'sinde {conversationId} öğesini konuşmanın kimliğiyle değiştirin.
İsteğin gövdesini, yanıtınızı temsil etmek için oluşturduğunuz bir Activity nesnesine ayarlayın.
Not
Bot Framework, botun gönderebileceği ileti sayısına herhangi bir kısıtlama getirmez. Ancak çoğu kanal, botların kısa bir süre içinde çok sayıda ileti göndermesini kısıtlamak için azaltma sınırları uygular. Buna ek olarak, bot birden çok iletiyi hızlı bir şekilde gönderirse kanal iletileri her zaman uygun sırayla işlemeyebilir.
Bir konuşma başlat
Botunuzun bir veya daha fazla kullanıcıyla konuşma başlatması gereken zamanlar olabilir. Kanaldaki bir kullanıcıyla konuşma başlatmak için botunuzun bu kanaldaki hesap bilgilerini ve kullanıcının hesap bilgilerini bilmesi gerekir.
İpucu
Botunuzun gelecekte kullanıcılarıyla konuşma başlatması gerekiyorsa, kullanıcı hesabı bilgilerini, kullanıcı tercihleri ve yerel ayar gibi diğer ilgili bilgileri ve hizmet URL'sini (Konuşma Başlatma isteğinde temel URI olarak kullanmak için) önbelleğe alın.
Bir konuşma başlatmak için şu isteği yayınlar:
POST /v3/conversations
İsteğin gövdesini botunuzun hesap bilgilerini ve konuşmaya eklemek istediğiniz kullanıcıların hesap bilgilerini belirten bir ConversationParameters nesnesine ayarlayın.
Not
Tüm kanallar grup konuşmalarını desteklemez. Bir kanalın grup konuşmalarını destekleyip desteklemediğini belirlemek ve bir kanalın konuşmada izin verdiği maksimum katılımcı sayısını belirlemek için kanalın belgelerine bakın.
Aşağıdaki örnekte, konuşma başlatan bir istek gösterilmektedir. Bu örnek istekte temel https://smba.trafficmanager.net/teams URI'yi temsil eder; bot sorunlarınızın farklı olabileceği isteklerin temel URI'sini temsil eder. Temel URI'yi ayarlama hakkında ayrıntılı bilgi için bkz. API Başvurusu.
POST https://smba.trafficmanager.net/teams/v3/conversations
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"bot": {
"id": "12345678",
"name": "bot's name"
},
"isGroup": false,
"members": [
{
"id": "1234abcd",
"name": "recipient's name"
}
],
"topicName": "News Alert"
}
Konuşma belirtilen kullanıcılarla oluşturulduysa, yanıt konuşmayı tanımlayan bir kimlik içerir.
{
"id": "abcd1234"
}
Botunuz daha sonra konuşma içindeki kullanıcılara ileti göndermek için bu konuşma kimliğini kullanabilir.