Nabaztag API

Using our API allows you to activate, from a third application, an event on your Nabaztag. For example: controlling the movement of the ears, commanding the LEDs, sending messages in TTS (text to speach) or with a Nabcast. Here are some of the things you can do with the Nabaztag API :

Send text messages to a rabbit Send choregraphies to a rabbit Send any nabcast to a rabbit Get the ear position of a rabbit Stream MP3 to your Nabaztag/tag (webradio, podcast or personal music) Retrieve information about the status of the rabbit and the account

Last update : May 08

Contents

Audience Activate reception of event on your Nabaztag How to send an event to a Nabaztag Choregraphy Language
r

1. Tempo command 2. Ear commands 3. LED commands 4. Combination of ear and LED commands 5. Choosing the voice for the TTS

Sending an URL to a Nabaztag/tag to get streaming audio Retrieving info from your Nabaztag Understanding return messages from the Nabaztag API Feedback

Audience
This document is intended for programmers who want to write client applications with Nabaztag.

Top

Activate reception of events on a Nabaztag

1. Go to the 'My Burrow / Preferences' section of your account on my.nabaztag.com
http://doc.nabaztag.com/api/home.html (1 de 9) [08/01/2009 19:52:25]

Top

Nabaztag API

2. Check 'Authorize the reception of external events', then OK. 3. The token is displayed
Please write down and save your token and serial number, as you must use it to send messages from your application. Note : If you deactivate and reactivate events, a new token will be sent to you.

How do I send an event?

You simply have to call the URL http://api.nabaztag.com/vl/FR/api.jsp with the following parameters : sn token Serial number of the Nabaztag that will receive events

Top

The token is a series of digits given when you activate the Nabaztag receiver. This extra identification limits the risks of spam, since, in order to send a message, you need to know both the serial number and the token The number of the message to send. This number can refer to a message in the Library or a personal MP3 file that you have downloaded. You find this identification number under the title of the track you are listening to Id of your nabcast (if you want to publish a content in your nabcast) Title of the post in your nabcast Position of the right ear between 0 and 16 (0 = ear vertical) Position of the left ear between 0 and 16 (0 = ear vertical) Send the position of the ears to your Nabaztag This is your application ID. It will allow you to authenticate the event's transmitter. This parameter is not yet in service. Allows you to choose the voice that will read the message Allows you to send a text configured for speech synthesis Sending a choreography to your Nabaztag The name of the choreography Allows you to define the length of time you want a message to remain on the site (in seconds). By default, the message will be stored for a period of two months See below for information on this parameter

idmessage

nabcast nabcasttitle posright posleft ears=ok idapp

voice tts chor chortitle ttlive

action

For example :
http://api.nabaztag.com/vl/FR/api. jsp?sn=00039D4022DE&token=112231049046144&posleft=0&posright=0&idmessage=10333&idapp=10

How do you send a message in text-to-speech (TTS) within a Nabcast that has the ID 52 with the title : myttsinmynabcast ?
http://api.nabaztag.com/vl/FR/api.jsp?.......nabcast=52&nabcasttitle=myttsinmynabcast&tts=the+nabcast

http://doc.nabaztag.com/api/home.html (2 de 9) [08/01/2009 19:52:25]

Nabaztag API

How do you send the message 10333 within the Nabcast with the ID 52 and a sound title of : mymp3inmynabcast ?
http://api.nabaztag.com/vl/FR/api.jsp? ....nabcast=52&nabcasttitle=mymp3inmynabcast&idmessage=10333
Please note that messages sent through the API have a lifetime of one day. Meaning they will be visible in your Nabaztag account and you will be able to replay them during one day.

Choregraphy Language
A choreography is a series of actions that you command the LEDs and ears to perform. The choreography's main parameter is an adjustable tempo. Once the tempo is set, actions will be sequenced to that rhythm. Each action is run at a precise moment, called "l'heure" (time) of the action : This time is expressed by the number of beats that have elapsed from the beginning of the choreography to the desired event. For example, with a tenth of a second tempo, the action associated with "l'heure" (time) '10' will happen a second after the beginning of the choreography. The action associated with "l'heure" '25' will happen 2.5 seconds after the beginning of the choreography... The choreography's syntax is a series of words or numbers, separated by commas. The numbers are always positive integers, expressed on a basis of 1 to 10. Words are one of two keywords : "motor" or "led". This series begins with the tempo value, and then continues on with a succession of motor or led actions. Each action (motor or led) begins with "l'heure" (time) (expressed by the number of beats that have elapsed from the beginning of the choreography to the desired event), followed by the command (motor or led), and a set of variables which describe the action. If two actions are commanded at the same time they will be carried out at the same time.

Top

1. Tempo command
The tempo is expressed in Hz."10" represents a tempo of a tenth of a second.

Top

2. Ears commands
This is a series of values separated by commas. The command is as follows : 1. First value : Action time (l'heure) "0" if it is the first command. 2. Second value : 'motor', to move an ear 3. Third value : Ears command 1 to command left ear 0 to command right ear 4. Fourth value : Angle of ear Possible value from 0 to 180 5. Fifth value : Unused, set at "0" 6. Sixth value : Rotation of the ears directions 1 : high->back->low->front->high... 0 : high->front->low->back->high... Example of a command that makes the left ear turn counter clockwise with a 20 angle, at l'heure (time) "0"
0,motor,1,20,0,0

Top

3. LED commands
It is a series of values separated by commas. 1. First value : action time (' l'heure ')
http://doc.nabaztag.com/api/home.html (3 de 9) [08/01/2009 19:52:25]

Top

Nabaztag API

("0" if it is the first command). 2. Second value : 'led' , which gives a color to the LED. 3. Third value : To define which LED you want to illuminate. 0 : bottom LED 1 : rabbit's left LED 2 : middle LED 3 : rabbit's right LED 4 : high LED 4. Fourth, Fifth, Sixth value : the color in RGB. Value from 0 to 255 Example : to make the middle LED go green, then the left one go red then the middle one turn off
0,led,2,0,238,0,2,led,1,250,0,0,3,led,2,0,0,0

4. Combination of ear and LED commands

To combine the three actions, with the initial tempo parameters :
10,0,motor,1,20,0,0,0,led,2,0,238,0,2,led,1,250,0,0,3,led,2,0,0,0

Top

5. Choose the voice for the TTS

You can choose the voice that will read your messages. French voices :

Top

FR-Anastasie FR-Archibald FR-Maxence ...

English voices :

UK-Mistermuggles UK-Shirley US-Bethany US-Billye ...

To get a complete list of the voices available, call the action #9 (see this section for more details)

Sending an URL to a Nabaztag/tag to get streaming audio

The API has gotten a boost in functionality and may now send URLs of MP3 files or feeds to a tag/tag. This new feature allows you to integrate your applications with MP3, podcast and webradio players. Now you can create application for your exceptionally talented rabbit with streaming audio ! How does it work ? If you have a tag/tag, you can use the API to send him MP3 hyperlinks to make him play podcasts or webradio. All you have to do is call or include your application in the URL
http://api.nabaztag.com/vl/FR/api_stream.jsp

Top

with the following settings : token : The token is a series of digits given when you activate Nabaztag's reception of external events. This identification limits the risk of spam since you must know the serial number and the token to send a message. sn : Serial number of the Nabaztag/tag that's going to receive the URLs urlList : URL address of the MP3 file that you want your Nabaztag/tag to read. If you wish to play several MP3 files in a row, you can can seperate them with this character | .
http://doc.nabaztag.com/api/home.html (4 de 9) [08/01/2009 19:52:25]

Nabaztag API

Example- play a webradio station :

http://api.nabaztag.com/vl/FR/api_stream.jsp?token=1267440739&sn= 0013D380FD3C&urlList=http://213.205.96.91:9915

If the MP3 feed is available, your tag/tag will play it. To play several mp3 streams, you must separate each URL with the character | .
http://api.nabaztag.com/vl/FR/api_stream.jsp?token=1267440739&sn= 0013D380FD3C &urlList=http://my.server.org/ music.mp3|http://m.server.org/music2.mp3

To understand the return messages from the api_stream.jsp, please refer to this section.

Retrieving info from your Nabaztag

Just as you send events to your Nabaztag, you can retrieve information from your user account or your Nabaztag himself. To do so, call the basis URL (http://api.nabaztag.com/vl/FR/api. jsp?sn=YOURSERIALNUMBERHERE&token=YOURTOKENHERE) and add the "action" parameter with the following values at the end of the URL. action=1 Preview the TTS or music (with music id) without sending it Sample :
<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>LINKPREVIEW</message> <comment>XXXX</comment> </rsp>

Top

action=2

Get a list of your friends Sample :

<?xml version="1.0" encoding="UTF-8"?> <rsp> <listfriend nb="1"/> <friend name="toto"/> </rsp>

action=3

Get a count and the list of the messages in your inbox Sample :
<?xml version="1.0" encoding="UTF-8"?> <rsp> <listreceivedmsg nb="1"/> <msg from="toto" title="my message" date="today 11:59" url="broad/001/948.mp3"/> </rsp>

action=4

Get the timezone in which your Nabaztag is set Sample :

<?xml version="1.0" encoding="UTF-8"?> <rsp> <timezone>(GMT) Greenwich Mean Time : Dublin, Edinburgh, Lisbon, London</timezone> </rsp>

action=5

Get the signature defined for the Nabaztag Sample :

<?xml version="1.0" encoding="UTF-8"?>

http://doc.nabaztag.com/api/home.html (5 de 9) [08/01/2009 19:52:25]

Nabaztag API

<rsp> <signature>XXXXX</signature> </rsp>

action=6

Get a count and the list of people in your blacklist Sample :

<?xml version="1.0" encoding="UTF-8"?> <rsp> <blacklist nb="1"/> <pseudo name="toto"/> </rsp>

action=7

Get to know if the Nabaztag is sleeping (YES) or not (NO) Sample :

<?xml version="1.0" encoding="UTF-8"?> <rsp> <rabbitSleep>YES</rabbitSleep> </rsp>

action=8

Get to know if the Nabaztag is a Nabaztag (V1) or a Nabaztag/tag (V2) Sample :

<?xml version="1.0" encoding="UTF-8"?> <rsp> <rabbitVersion>V1</rabbitVersion> </rsp>

action=9

Get a list of all supported languages/voices for TTS (text to speach) engine Sample :
<?xml version="1.0" encoding="UTF-8"?> <rsp> <voiceListTTS nb="2"/> <voice lang="fr" command="FR-Anastasie"/> <voice lang="de" command="DE-Otto"/> </rsp>

action=10

Get the name of the Nabaztag Sample :

<?xml version="1.0" encoding="UTF-8"?> <rsp> <rabbitName>nabmaster</rabbitName> </rsp>

action=11

Get the languages selected for the Nabaztag Sample :

<?xml version="1.0" encoding="UTF-8"?> <rsp><langListUser nb="4"/> <myLang lang="fr"/> <myLang lang="us"/> <myLang lang="uk"/> <myLang lang="de"/> </rsp>

http://doc.nabaztag.com/api/home.html (6 de 9) [08/01/2009 19:52:25]

Nabaztag API

action=12

Get a preview of a message. This works only with the urlPlay parameter and URLs like broad/001/076/801/262.mp3 Sample :
<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>LINKPREVIEW</message> <comment>XXXX</comment> </rsp>

action=13

Send your Rabbit to sleep

<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>COMMANDSENT</message> <comment>You rabbit will change status</comment> </rsp>

action=14

Wake up your Rabbit

<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>COMMANDSENT</message> <comment>You rabbit will change status</comment> </rsp>

Understanding the return messages from the Nabaztag API

Top

Too much requests sent :

<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>ABUSESENDING</message> <comment>Too many messages sent in the allowed time try again later please</comment> </rsp>

Wrong token or serial number :

<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>NOGOODTOKENORSERIAL</message> <comment>Your token or serial number are not correct !</comment> </rsp>

Wrong music id (either not in your personal MP3s list or not existing)
<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>MESSAGENOTSENT</message> <comment>Your message id is not correct or is private</comment> </rsp>

Nabcast not posted because music id is not part of your personal MP3s or the nabcast does not exist
<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>NABCASTNOTSENT</message> <comment>Your nabcast id is not correct or is private</comment> </rsp>

http://doc.nabaztag.com/api/home.html (7 de 9) [08/01/2009 19:52:25]

Nabaztag API

Nabcast posted
<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>NABCASTSENT</message> <comment>Your nabcast has been sent</comment> </rsp>

Message sent
<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>MESSAGESENT</message> <comment>Your message has been sent</comment> </rsp>

Message not sent

<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>MESSAGENOTSENT</message> <comment>Your message id is not correct or is private</comment> </rsp>

TTS message sent

<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>TTSSENT</message> <comment>Your text has been sent</comment> </rsp>

TTS creation problem

<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>TTSNOTSENT</message> <comment>Your text could not be sent</comment> </rsp>

Choregraphy message sent

<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>CHORSENT</message> <comment>Your chor has been sent</comment> </rsp>

Choregraphy message not sent because the "chor" command was incorrect
<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>CHORNOTSENT</message> <comment>Your chor could not be sent (bad chor)</comment> </rsp>

Ears position sent

<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>EARPOSITIONSENT</message> <comment>Your ears command has been sent</comment> </rsp>

Ears position not sent because the given position is incorrect

<?xml version="1.0" encoding="UTF-8"?>

http://doc.nabaztag.com/api/home.html (8 de 9) [08/01/2009 19:52:25]

Nabaztag API

<rsp> <message>EARPOSITIONNOTSENT</message> <comment>Your ears command could not be sent</comment> </rsp>

Getting the ears position

<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>POSITIONEAR</message> <leftposition>8</leftposition> <rightposition>10</rightposition> </rsp>

URL was sent (api_stream)

<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>WEBRADIOSENT</message> <comment>Your webradio has been sent</comment> </rsp>

URL was not sent (api_stream)

<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>WEBRADIONOTSENT</message> <comment>Your webradio could not be sent</comment> </rsp>

urlList parameter missing (api_stream)

<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>NOCORRECTPARAMETERS</message> <comment>Please check urlList parameter !</comment> </rsp>

The rabbit is not a Nabaztag/tag

<?xml version="1.0" encoding="UTF-8"?> <rsp> <message>NOTV2RABBIT</message> <comment>V2 rabbit can use this action</comment> </rsp>

Feedback
If you have questions, remarks, suggestions regarding the Nabaztag API or if you developped a nice application and want to submit it to us (so that we can promote you on our website), contact us at api [at] violet.net Navigation
Contents Activate reception of events How do I send an event? Choregraphy language - Stream a URL to Nabaztag/tag - Retrieving info from your Nabaztag - Understanding answers from the API

Top

Learn more
www.nabaztag.com my.nabaztag.com help.nabaztag.com

http://doc.nabaztag.com/api/home.html (9 de 9) [08/01/2009 19:52:25]