☂️(Unofficial) Build your skill for Yandex.Alice with ease. (nodejs/typescript)
Clone or download
Latest commit d715ab4 Jan 17, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Stage and Scene were imported Nov 12, 2018
src Fix code style Oct 27, 2018
tests Fix code style Oct 27, 2018
.gitignore feat: improve alice.ts Jul 1, 2018
.prettierrc fix: update codestyle Aug 3, 2018
CHANGELOG.md 2.0.2 Aug 31, 2018
LICENSE Initial commit Mar 17, 2018
README.md Fix type in readme Jan 8, 2019
jest.config.js fix: tests codestyle, remove redundant Aug 12, 2018
package.json Fix code style Oct 27, 2018
tsconfig.json Fix code style Oct 27, 2018
tslint.json Fix code style Oct 27, 2018

README.md

yandex-dialogs-sdk

npm version

Note: this is an open-source project. It is not affiliated with Yandex LLC.

Tiny zen library to create skills for Yandex.Alice

yandex-dialogs-sdk — Telegram chat, if you need help

Install SDK

npm i yandex-dialogs-sdk --save

To enable debug mode run DEBUG=yandex-dialogs-sdk node YOUR_APP.js

Videotutorials

🔨 Built with SDK

Getting Started

const { Alice, Reply, Markup } = require('yandex-dialogs-sdk')
const alice = new Alice();

const M = Markup;
alice.command('', async ctx => Reply.text('Look, what i can!'));
alice.command('Give a piece of advice', async ctx =>
  Reply.text('Make const not var'),
);
alice.command(
  ['What is trending now?', 'Watch films', 'Whats in the theatre?'],
  ctx => {
    return {
      text: `What about 50 Angry Men?`,
      buttons: [M.button('Buy ticket'), M.button('What else?')],
    };
  },
);
alice.command(/(https?:\/\/[^\s]+)/g, ctx => Reply.text('Matched a link!'));
alice.any(async ctx => Reply.text(`I don't understand`));
const server = alice.listen(3001, '/');

Hot middlewares from maintainer

Handle non-trivial scenarios

const { Alice, Scene, Stage } = require('yandex-dialogs-sdk')
const stage = new Stage();
const alice = new Alice();
const SCENE_AT_BAR = 'SCENE_AT_BAR';
const atBar = new Scene(SCENE_AT_BAR);

atBar.command('show menu', ctx =>
  Reply.text('only vodka here', {
    buttons: ['buy vodka', 'go away'],
  }),
);
atBar.command('buy vodka', ctx => Reply.text(`you're dead`));
atBar.command('go away', ctx => {
  ctx.leave();
  return Reply.text('as you want');
});
atBar.any(ctx => Reply.text(`no money no honey`));

stage.addScene(atBar);
alice.use(stage.getMiddleware());
alice.command('i want some drinks', ctx => {
  ctx.enter(SCENE_AT_BAR);
  return Reply.text('lets go into pub', {
    buttons: ['show menu', 'go away'],
  });
});

A lot of examples in folder ./examples

API

Alice
const { Alice } = require('yandex-dialogs-sdk')
  • alice.command - Set handler for command
  • alice.any - Set handler if no command has been matched
alice.command('text', ctx => null)
alice.command(/regex/ig, ctx => null)
alice.command(['array', 'of', 'strings'], ctx => null)
// pass function which returns boolean. True means perfect match.
alice.command(ctx => true || false, ctx => null)

alice.any('text', ctx => null)
Images Api

To use this API you have to provide your auth data. More info

const alice = new Alice({
  oAuthToken: OAUTH_TOKEN,
  skillId: SKILL_ID
});
  • alice.imagesApi.uploadImageByUrl - Upload image by URL
  • alice.imagesApi.uploadImageFile - Upload image by File Buffer (Not implemented yet).
  • alice.imagesApi.getImages - Get all uploaded images
  • alice.imagesApi.getImagesQuota - Get images quota
  • alice.imagesApi.deleteImage - Delete image
const image = await alice.imagesApi.uploadImageByUrl(IMAGE_URL);
const images = await alice.imagesApi.getImages();
// @example { total: 104857600, used: 25715766 }
const quota = await alice.imagesApi.getImagesQuota();
// @example { result: 'ok' } | { message: 'Image not found' }
await alice.imagesApi.deleteImage('IMAGE_ID')
Context
  • [ctx.data] - object with request
  • [ctx.message] — shortcut for ctx.data.request.command
  • [ctx.originalUtterance] - shortcut for ctx.data.request.original_utterance
  • [ctx.sessionId] — shortcut for ctx.data.session.session_id
  • [ctx.messageId] — shortcut for ctx.data.session.message_id
  • [ctx.userId] — shortcut for ctx.data.session.user_id
  • [ctx.payload] — shortcut for ctx.data.request.payload
  • [ctx.nlu] - shortcut for ctx.data.request.nlu (see more)
  • [ctx.enter] - enters session
  • [ctx.leave] - goes to main dialog
  • ctx.session.set - set session value. Session is attached to user_id
  • ctx.session.get - get session value.
// enter/leave scene
const { Scene } = require('yandex-dialogs-sdk');
ctx.enter('scene-name');
ctx.leave();

ctx.session.set('price', 200);
const price = ctx.session.get('price'); // 200

enter/leave example

Stage
const { Stage } = require('yandex-dialogs-sdk')
const stage = new Stage()
  • stage.addScene - adds scene to stage
  • stage.removeScene - removes scene from stage
  • stage.getMiddleware - returns stage middleware

full scene example

Middlewares
const createMessagesCounterMiddleware = () => {
  let count = 0
  return async (ctx, next) => {
    // You can do anything with context here
    count += 1;
    return next(ctx)
  }
}
alice.use(createMessagesCounterMiddleware())
Reply
const { Reply } = require('yandex-dialogs-sdk')
IMAGE_ID = '213044/d13b0d86a41daf9de232'
EXTRA_PARAMS = { // Extra params are optional
  tts: 'Hi the+re',
  buttons: ['one', Markup.button('two')],
  end_session: true
}
  • Reply.text
// Second argument is optional
alice.any(ctx => Reply.text('text'), EXTRA_PARAMS)
  • Reply.bigImageCard - One big image
Reply.bigImageCard('text', {
  image_id: IMAGE_ID,
  title: string, // optional
  description: string, // optional
  button: M.button('click'), // optional
}, EXTRA_PARAMS)
  • Reply.itemsListCard - Gallery
Reply.itemsListCard('text', [IMAGE_ID, IMAGE_ID], EXTRA_PARAMS);
Reply.itemsListCard('test', {
    header: 'header',
    footer: {
      text: 'test',
      button: Markup.button('button'),
    },
    items: [
      IMAGE_ID, 
      { image_id: IMAGE_ID, title: 'title', description: 'description' },
    ],
  });
Markup
const { Markup } = require('yandex-dialogs-sdk')
  • Markup.button
const M = Markup
M.button('string')
M.button({
  title: string;
  url: string;
  payload: object;
  hide: boolean;
})

CONTRIBUTING

git clone

npm install && npm run test && npm run dev

Typescript will be compiled into ./dist

Contributors

Thanks all these awesome people for this product.


Stanislav Popov

📖

Nikita Rogozhin

📖

Roman Paradeev

📖

Vanya Klimenko

📖

Dmitry Guketlev

📖

Alexander Karpov

📖

Phil Romanov © MIT 2018