[sequences] provide bot apis to be used by apps

[rhwy]

In order to centralise the bots source of truth and avoid doing different implementations of the same thing, we want to have bot apis that can do the same actions that we have in bots but to be used by client apps.

TL;DR

• UserProperties :
  • set user property : http://api.cvd.io/botapis/user/setproperty
  • get user property: http://api.cvd.io/botapis/user/property
  • get all user properties : http://api.cvd.io/botapis/user/properties
• Sequences :
  • get one fragment by Id or tag : http://api.cvd.io/botapis/sequences/fragment
  • get next sequence for user : http://api.cvd.io/botapis/sequences/next

Note for the following apis that:

• a botName must be provided to identify the context you're working on (the name of the bot not the app name)
• a deviceid and a facebook id should always be provided, at least one of them will be mandatory. If you have both, send both for information but facebook id will be used to identify users, if you have only one it will be used as unique id.

User Properties

In order to do some specific actions and decisions on the bot engine, bot apis need to know the user profile properties. The idea is to call these apis from the clients (along with the usual SetUserProperty sent with events)

SET

I want to set a user property for a user using a Bot:

POST http://api.cvd.io/botapis/user/setproperty
 {
     "BotName" : "test", 
     "DeviceId" : "123", 
     "FacebookId" : "456", 
     "PropertyName": "greeting", 
     "PropertyValue" : "Hello" 
}

You’ll get in return either

• an Http OK
• an Http NotFound

GET

I want to get a user property for a user using a bot:

POST http://api.cvd.io/botapis/user/property
{ 
   "BotName" :"test", 
   "DeviceId" : "123", 
   "FacebookId" : "456", 
    "PropertyName" : "greeting" 
}

You’ll get in return either

• an Http OK with an object with {PropertyName,PropertyValue}
• an Http NotFound there is no match for user/bot/property

GET ALL

I want to get all properties for a user using a Bot

POST http://api.cvd.io/botapis/user/properties
{ 
   "BotName" : "test", 
   "DeviceId" : "123", 
   "FacebookId" : "456"
}

You’ll get in return either

• an Http OK with a list of key/value pairs for this this user
• an Http NotFound if there is no matching values for bot/device

Fragments

By ID

I want to get a specific sequence Fragment by it’s ID:

POST http://api.cvd.io/botapis/sequences/fragment
{ 
   "BotName":"test", 
    "DeviceId" : "123", 
    "FacebookId": "456", 
    "ParentSequencePath":"HowAreYou",
    "FragmentId" : "funnySequence"
}

You’ll get in return either

• an Http OK with the Json sequence
• an Http NotFound

Note:

• ParentSequencePath : is the sequence path you're actually executing that is referencing the fragment. a sequence path is the combination of all elements representing your position in the sequence tree sequenceId/subElementId/subElementId
• this SequencePath is not actually used for finding the fragment but it is a useful information for further understanding of the executed conversation

By TAG

I want to get a random sequence Fragment by Tag(s):

POST http://api.cvd.io/botapis/sequences/fragment
{ 
   "BotName":"test", 
   "DeviceId": "123", 
   "FacebookId": "456", 
   "ParentSequencePath":"HowAreYou",
   "Tags" : ["funny","penguins"]
}

You’ll get in return either

• an Http OK with the Json sequence
• an Http NotFound

Sequences

I want to get the next sequence:

POST http://api.cvd.io/botapi/sequences/next
{ 
   "BotName":"test", 
   "DeviceId": "123", 
   "FacebookId": "456", 
   "LastSequenceId":"BeyonceOrRihanna"
}

You’ll get in return either

• an Http OK with the Json sequence
• an Http NotFound

Note:

• LastSequenceId : is optional and is the id of the sequence you've just finished
• the next sequence is calculated based on the order of the referenced sequences in the master file, the information on your profile and the history of the previously executed sequences.
• each time you call the service and that the service provides you a new sequences it will be added to user's history of executed sequences.

[andreasdieryck]

Sounds great @rhwy.

I have one small remark regarding the Fragments call:

In your example, to get a fragment, you use the pair "FragmentId" : "funnySequence". Until now, we have used "FragmentPath" : "funnySequence" to refer to a Fragment in the sequence. Could we homogenise this one way or another?

@Frederikos does it sound good to you too?

[rhwy]

you're right, for me the FragmentPath is a more generic thing that we should use. if you refer the root of the sequence you'll have fragmentPath = fragmentId, but in case we need to refer a specific element within a sequence (a children element node/leaf in the sequence tree) you can access it by it's path which is a composition of the ids of all elements in the path (ex= funnySequence/ShowMeThePenguins/Yes). I'll update the apis/doc in that way

[rhwy]

also, we have ParentSequenceIdmaybbe it should be interesting to use ParentSequencePath instead? one important feature it can bring us is knowing exactly where in the original sequence was the call to fragments. it allows us to see the impact if we arrive on the fragment by one path or another (if we link to the same fragment after a question for exemple) or if we decide to test the impact of adding one question before another or anything in that way.

what do you think?

[andreasdieryck]

Makes more sense that way indeed. @Frederikos is it all clear to you as well?