<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE xep SYSTEM 'xep.dtd' [ <!ENTITY % ents SYSTEM 'xep.ent'> %ents; ]> <?xml-stylesheet type='text/xsl' href='xep.xsl'?> <xep><header> <title>Simple Buttons</title> <abstract>This specification provides a way to send simple buttons.</abstract> &LEGALNOTICE; <number>xxxx</number> <status>ProtoXEP</status> <type>Standards Track</type> <sig>Standards</sig> <dependencies> <spec>XMPP Core</spec> </dependencies> <supersedes/> <supersededby/> <shortname>NOT_YET_ASSIGNED</shortname> <author> <firstname>Kim</firstname> <surname>Alvefur</surname> <email>zash@zash.se</email> <jid>zash@zash.se</jid> </author> <revision> <version>0.0.2</version> <date>2018-09-30</date> <initials>ka</initials> <remark>Polishing preparing for submission</remark> </revision> <revision> <version>0.0.1</version> <date>2018-09-02</date> <initials>ka</initials> <remark>Initial version</remark> </revision> </header> <section1 anchor="intro" topic="Introduction"> <p>Having actionable buttons in chats is apparently a fashionable thing now. This specification defines a simple protocol for buttons and responses.</p> </section1><section1 anchor="reqs" topic="Requirements"> <ul> <li>To provide a representation of a simple button or two in a chat.</li> </ul> <section2 anchor="todo" topic="TODO"> <ul> <li>Is "button" too UI-centric? <ul> <li>Could base it on the <tt><action></tt> element from ad-hoc?</li> </ul></li> <li>Styling? Maybe a few fixed styles like normal, warning, danger?</li> </ul> </section2></section1><section1 anchor="glossary" topic="Glossary"> <p>OPTIONAL.</p> <dl> <di><dt>Button</dt> <dd>An actionable object that can be invoked.</dd></di> <di><dt>Click</dt> <dd>The act of invoking the actionable object.</dd></di> </dl> </section1><section1 anchor="usecases" topic="Use Cases"> <p>A chat bot wants to provide fixed choice answers or commands.</p> </section1><section1 anchor="elements" topic="Elements"> <section2 anchor="button-element" topic="Button element"> <p>A button is represented by a <tt><button></tt> element in the <tt>urn:xmpp:tmp:buttons</tt>.</p> <example><![CDATA[<button xmlns="urn:xmpp:tmp:buttons" value="button-clicked"> <label xml:lang="en">Click me</label> </button>]]></example> <dl> <di><dt>value</dt> <dd>Textual payload to be sent in a message <tt><body></tt> when the button is clicked.</dd></di> <di><dt><label></dt> <dd>Text label for the button. Can be repeated per language.</dd></di> </dl> </section2></section1><section1 anchor="protocol" topic="Protocol"> <section2 anchor="sending-a-button" topic="Sending a button"> <p>A message with buttons is sent by including one or more <button> elements with distinct value attributes. At least one <label> element MUST be included containing a textual description for the button.</p> <example><![CDATA[<message from="memberbot@example.com"> <body xml:lang="en">Approve? (yes/no)</body> <button xmlns="urn:xmpp:tmp:buttons" value="yes"> <label xml:lang="en">Yes</label> <label xml:lang="sv">Ja</label> </button> <button xmlns="urn:xmpp:tmp:buttons" value="no"> <label xml:lang="en">No</label> <label xml:lang="sv">Nej</label> </button> </message>]]></example> <p>A single message MUST NOT have multiple buttons with the same <tt>@value</tt>.</p> </section2><section2 anchor="clicking-a-button" topic="Clicking a button"> <p>When the user clicks a button, their client sends a plain text message body containing the <tt>@value</tt> as <body> text.</p> <example><![CDATA[<message to="memberbot@example.com"> <body>yes</body> </message>]]></example> </section2></section1><section1 anchor="rules" topic="Business Rules"> <p>OPTIONAL. TODO.</p> </section1><section1 anchor="impl" topic="Implementation Notes"> <p>OPTIONAL. TODO.</p> </section1><section1 anchor="access" topic="Accessibility Considerations"> <p>Accessibility for whom?</p> </section1><section1 anchor="i18n" topic="Internationalization Considerations"> <p>Multiple instances of the <tt><label/></tt> element MAY be included for the purpose of providing alternate versions of the same text in different languages, i.e. with distinct <tt>xml:lang</tt> attributes.</p> </section1><section1 anchor="security" topic="Security Considerations"> <p>Do not press the big red button marked "Danger: Do Not Push".</p> </section1><section1 anchor="iana" topic="IANA Considerations"> <p>None.</p> </section1><section1 anchor="registrar" topic="XMPP Registrar Considerations"> <p>Register the namespace etc.</p> </section1><section1 anchor="schema" topic="XML Schema"> <p>REQUIRED for protocol specifications.</p> <code><![CDATA[button @value : string label+ : string]]></code> </section1> </xep>