yandex-dialogs-sdk

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

• Роман Парадеев — Доклад с конференции «В гостях у Алисы»
• Фил Романов — Пишем игру Guess Number за 10 минут

🔨 Built with SDK

• yandex-dialogs-whatis Smart reminder by @popstas
• Алиса в стране диез Awesome music game by @AntonRzevskiy
• Adventure Engine Adventure quest game by @Teoreez
• uraljs-alice-bot Навык Алисы UralJS
• homebot-alisa
• Send PR to be here!

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

• yandex-dialogs-sdk-lowdb - store your users sessions in file
• yandex-dialogs-sdk-chatbase - send events to Google Chatbase by @popstas

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

• Yandex Dialogs Protocol

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)

// create event listener
// triggers when request processing is finished
alice.on('response', ctx => {
  console.log(ctx.response)
})

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.response] - available only in listeners. appears just before sending a response
• [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' },
    ],
  });

Events

// create event listener
// triggers when request processing is finished
alice.on('response', ctx => {
  console.log(ctx.response)
})

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