Components

Components are used to send messages to users.

Examples

All variables you can import from @urban-bot/core. Don't forget to import React everywhere you use JSX syntax.

import React from 'react'; 
import { render, Root, Text } from '@urban-bot/core';  

const React = require('react');
const { render, Root, Text } = require('@urban-bot/core');

Navigation

render

The main function that starts React. Works similar ReactDOM.render.

Instance of Root component.

required

Root

render(  
    <Root bot={new UrbanBotTelegram(options)}>  
        <YourApp />    
    </Root>  
);

Callback

It's called when your app is initialized.

optional

Function

render(  
    ...,  
    () => console.log('App has started')
);

Common props

isNewMessageEveryRender

If true, a new message is sent after every state update. If false, a message is sent one time and edited next state updates.

optional

boolean

function Example() {
    const [text, setText] = React.useState('1');

    return <Text isNewMessageEveryRender>{text}</Text>
}

// setText('2')
// setText('3')

// chat:
// bot write: '1'
// bot write: '2'
// bot write: '3'

function Example() {
    const [text, setText] = React.useState('1');

    return <Text isNewMessageEveryRender={false}>{text}</Text>
}

// setText('2')
// setText('3')

// chat:
// bot write: '3'

title

A text is sent with the main message.

optional

HTML

<Image title="some text" />  

<Image title={<b>some text</b>} />

buttons

Buttons are attached to a message.

optional

ButtonGroup

<Image
    file={image}
    buttons={  
        <ButtonGroup>  
            <Button onClick={() => setUrl(nextImage)}>Next</Button>  
            <Button onClick={() => setUrl(prevImage)}>Previous</Button>  
        </ButtonGroup>  
    }  
/>

simulateTyping

Simulate typing before sending a message, pass as milliseconds.

optional

number

<Text simulateTyping={1000}>
    This message will be sent after 1 second and a user see a bot types before sending.
</Text>

parseMode

The markup language which is used for parsing text. Calculated automatically for every messenger, but you can specify directly.

optional

'HTML' | 'markdown'

// '<b>bold</b>'
<Text parseMode="HTML">
    <b>bold</b>
</Text> 

// '*bold*'
<Text parseMode="markdown">
    <b>bold</b> 
</Text> 

// '*bold*'
<Image parseMode="markdown" title={<b>bold</b>} />

You can pass usual text with ready formatting.

<Text parseMode="HTML">{'<b>bold</b>'}</Text>

<Text parseMode="markdown">*bold*</Text>

disableNotification

Sending a message silently.

optional

boolean

<Text disableNotification>Mam, I will be late today</Text>

replyToMessageId

Specify if you want to send a message as a reply to another message.

optional

string | number

<Text replyToMessageId="some-id">Yes, I agree!</Text>

personaId

Some messengers support sending messages from different persons inside one chat.

optional

string | number

<Text personaId="natalie-id">Hi, I am Natalie. How can I help you?</Text>

forceReply

After sending a message, next user message automatically will be reply to the sent message.

optional

boolean

<Text forceReply>What's your name?</Text>

HTML

You can format text with these tags.

Plain text

string | number

Bold
<b>bold</b>
<strong>bold</strong>
Italic
<i>italic</i>
<em>italic</em>
Underline
<u>underline</u>
<ins>underline</ins>
Strikethrough
<s>strikethrough</s>
<strike>strikethrough</strike>
<del>strikethrough</del>
Code
<code>code</code>
<pre>code</pre>
Quote text
<q>text</q>
Link
<a href="https://github.com/urban-bot/urban-bot">Link</a>
Line break
<br />

Root

A required component which you should wrap over your application. It connects specific messenger to the core, provides the main context, manages multiple chats, and start the server.

render(  
    <Root bot={new UrbanBotTelegram(options)}>  
        <YourApp />    
    </Root>  
);

For multiple messengers, you should create several Root.

render(  
    <Root bot={new UrbanBotTelegram(options)}>  
        <YourApp />    
    </Root>  
);  
render(  
    <Root bot={new UrbanBotFacebook(options)}>  
        <YourApp />  
    </Root>  
);

children

Entry point of your app.

required

ReactNode

function YourApp() {  
   return <Text>Hello World!</Text>;  
}
  
render(  
    <Root bot={new UrbanBotTelegram(options)}>  
        <YourApp />    
    </Root>  
);

bot

An instance of specific UrbanBot.

required

UrbanBotTelegram | UrbanBotDiscord | UrbanBotFacebook | UrbanBotSlack

import { UrbanBotTelegram } from '@urban-bot/telegram';
  
render(  
    <Root bot={new UrbanBotTelegram(options)}>  
        <YourApp />    
    </Root>  
);

sessionTimeSeconds

After this time a user session is clear.

optional
default 60 * 60 * 24 * 7

number

render(  
    <Root sessionTimeSeconds={Infinity}>  
        <YourApp />    
    </Root>  
);

port

Port to start server.

optional
default 8080

number

render(  
    <Root port={3000}>  
        <YourApp />    
    </Root>  
);

If you use several messengers you can use the same or use a unique port for each.

render(  
    <Root bot={new UrbanTelegramBot(options)} port={3000}>  
        <YourApp />    
    </Root>  
);

render(  
    <Root bot={new UrbanSlackBot(options)} port={3000}>
        <YourApp /> 
    </Root>  
);

render(  
    <Root bot={new UrbanFacebookBot(options)} port={4000}>
        <YourApp />    
    </Root>  
);

isNewMessageEveryRender

Default value for all urban-bot components under Root.

default true
function MyAudio() {
    return <Audio file="/some-audio.mp3" />
}

render(
    <Root isNewMessageEveryRender={false}>  
        <Text>some text</Text>
        <Image file="https://path-to-image.jpg" />
        <MyAudio />
    </Root>  
); 

// Text, Image, Audio are with isNewMessageEveryRender={false}

parseMode

Default value for all urban-bot components under Root.

Router

Separate different parts of your application by Router.

function Profile() {
    return ...
}

function Catalog() {
    return ...
}

function App() {
    return (
        <Router>
            <Route path="profile">  
                <Profile />  
            </Route>
            <Route path="catalog">  
                <Catalog />  
            </Route>
        </Router>
    );
}

Now if a user type 'profile' or 'catalog' urban-bot renders a corresponding component.

Also, you can navigate inside your app without messaging by using a router context useRouter.

function ProfileButtons() {
    const { navigate } = useRouter();

    return (
        <ButtonGroup>
            <Button onClick={() => navigate('catalog')}>Go to Catalog</Button>
        </ButtonGroup>
    );
}

children

One or many Route components.

required

Route

historyLength

Maximum of saved navigated router paths. You can get history using useRouter hook.

optional
default 5

number

<Router historyLength={30}>
    ...
</Router>

withInitializeCommands

If you pass commands to path prop every specific bot can initialize them. For example auto-suggesting command if a user starts to type it.

optional
default false
<Router withInitializeCommands>
    ...
</Router>

Route

Piece of Router.

<Route path="profile">  
    <Profile />
</Route>

children

Part of your application.

required

ReactNode

path

String or regexp which is connected with Route children. To get router params use useRouter.

required

string | RexExp

<Route path="profile">
    ...
</Route>

<Route path="/profile">
    ...
</Route>

<Route path="/profile/:id">
    ...
</Route>

<Route path={/.+/}>
    <Text>Not found</Text>
</Route>

description

Describe your Route. It is usually needed for withInitializeCommands.

optional

string

<Route path="profile" description="Some information about you">
    ...
</Route>

Text

Send a text message to a chat.

<Text>Some text<Text>

children

Plain text or supported HTML tags.

required

HTML

<Text>      
    Usual text      
    <br />      
    <b>Bold text</b>      
    <br />      
    <i>Italic text</i>      
    <b>      
        Bold and <s>Strikethrough text</s>      
    </b>  
    ...  
</Text>

disableWebPagePreview

Some messengers show web page preview if you attach a link in your text. Set to true if you want to disable this behavior.

optional

boolean

<Text disableWebPagePreview>  
    <a href="https://github.com/urban-bot/urban-bot">link</a>
<Text>

isNewMessageEveryRender

simulateTyping

parseMode

disableNotification

replyToMessageId

personaId

forceReply

ButtonGroup

Required wrapper for buttons.

<ButtonGroup>  
    <Button onClick={() => console.log('Click first')}>First</Button>  
    <Button onClick={() => console.log('Click second')}>Second</Button>  
</ButtonGroup>

children

An instance or instances of Button.

required

Button | Button[] | Button[][]

<ButtonGroup title="Button">  
    <Button>First</Button>  
</ButtonGroup>  

<ButtonGroup title="Buttons">  
    <Button>First</Button>  
    <Button>Second</Button>  
</ButtonGroup>  

<ButtonGroup title="Matrix Buttons">  
    {[  
        [<Button>First button</Button>, <Button>Second button</Button>],  
        [<Button>Third button</Button>, <Button>Fourth button</Button>],  
    ]}  
</ButtonGroup>

maxColumns

Maximum buttons in one line.

optional

number

<ButtonGroup title="Buttons" maxColumns={2}>  
    <Button>1</Button>  
    <Button>2</Button>
    <Button>3</Button>  
    <Button>4</Button>  
</ButtonGroup>

Will be shown as:

<Button>1</Button><Button>2</Button>
<Button>3</Button><Button>4</Button>

isResizedKeyboard

Not stretch buttons for all keyboard size.

optional

boolean

<ButtonGroup isResizedKeyboard>
    <Button>Resized</Button>
</ButtonGroup>

isReplyButtons

Send button name as text after every click.

optional

boolean

If a user clicks on the button, he automatically sends 'Hello' message.

<ButtonGroup isReplyButtons>
    <Button>Hello</Button>
</ButtonGroup>

title

isNewMessageEveryRender

simulateTyping

parseMode

disableNotification

replyToMessageId

personaId

forceReply

Button

Button, just button. Should be wrapped by ButtonGroup.

<Button>Text</Button>

children

Button name.

required

string

onClick

Callback is called after click.

optional

Function

<Button onClick={() => console.log('Click first')}>First</Button>

url

The web page is opened after a click.

optional

string

<Button url="http://some-url.com">Open a web page</Button>

phoneNumber

The phone number is suggested to call after a click.

optional

string | number

<Button phoneNumber="+71234567890">Call Saul Goodman</Button>

id

The unique id. If you don't specify it, it is generated automatically.

optional

string

<Button id="some-id">First</Button>

Image

Send an image to a chat.

<Image file="https://path-to-image.png" />

file

File id or URL or Stream or Buffer.

required

string | Buffer | ReadableStream

<Image file="id123" />  

<Image file="https://path-to-image.png" />  

<Image file={fs.createReadStream('/files/image.jpg')} />  

<Image file={fs.readFileSync('/files/image.jpg')} />

name

optional

string

<Image name="a big cat" />

alt

Text if an image is not displayed.

optional

string

<Image alt="This is cat" />

title

buttons

isNewMessageEveryRender

simulateTyping

parseMode

disableNotification

replyToMessageId

personaId

forceReply

Video

Send a video to a chat.

<Video file="https://path-to-video.mp4" />

file

File id or URL or Stream or Buffer.

required

string | Buffer | ReadableStream

<Video file="id123" />

<Video file="https://path-to-video.mp4" />

<Video file={fs.createReadStream('/files/video.mp4')} />

<Video file={fs.readFileSync('/files/video.mp4')} />

name

optional

string

<Video name="I'm a cook" />

author

optional

string

<Video author="Leeroy Jenkins" />

width

optional

number

<Video width={200} />

height

optional

number

<Video height={200} />

duration

optional

number

<Video duration={10} />

title

buttons

isNewMessageEveryRender

simulateTyping

parseMode

disableNotification

replyToMessageId

personaId

forceReply

Audio

Send an audio to a chat.

<Audio file="https://path-to-audio.mp3" />

file

File id or URL or Stream or Buffer.

required

string | Buffer | ReadableStream

<Audio file="id123" />

<Audio file="https://path-to-audio.mp3" />

<Audio file={fs.createReadStream('/files/audio.mp3')} />

<Audio file={fs.readFileSync('/files/audio.mp3')} />

name

optional

string

<Audio name="Morning Mood" />

author

optional

string

<Audio author="Edvard Grieg" />

duration

optional

number

<Audio duration={10} />

title

buttons

isNewMessageEveryRender

simulateTyping

parseMode

disableNotification

replyToMessageId

personaId

forceReply

Animation

Send an animation to a chat.

<Animation file="https://path-to-animation.gif" />

file

File id or URL or Stream or Buffer.

required

string | Buffer | ReadableStream

<Animation file="id123" />

<Animation file="https://path-to-audio.gif" />

<Animation file={fs.createReadStream('/files/animation.gif')} />

<Animation file={fs.readFileSync('/files/animation.gif')} />

name

optional

string

<Animation name="Say my name" />

duration

optional

number

<Animation duration={10} />

width

optional

number

<Animation width={200} />

height

optional

number

<Animation height={200} />

title

buttons

isNewMessageEveryRender

simulateTyping

parseMode

disableNotification

replyToMessageId

personaId

forceReply

File

Send a file to a chat.

<File file="https://path-to-file.pdf" />

file

File id or URL or Stream or Buffer.

required

string | Buffer | ReadableStream

<File file="id123" />

<File file="https://path-to-file.pdf" />

<File file={fs.createReadStream('/files/file.pdf')} />

<File file={fs.readFileSync('/files/file.pdf')} />

name

optional

string

<File name="report_21.03.15" />

title

buttons

isNewMessageEveryRender

simulateTyping

parseMode

disableNotification

replyToMessageId

personaId

forceReply

Media

Send a group of media files.

<Media
    files={[
        {
            type: 'image',
            file: 'https://path-to-image1.jpg',
            title: 'image1'
        },
        {
            type: 'image',
            file: 'https://path-to-image2.jpg',
            title: 'image2'
        }
    ]}
/>

files

required

Media File[]

isNewMessageEveryRender

simulateTyping

parseMode

disableNotification

replyToMessageId

personaId

forceReply

Media File

type

required

'image' | 'video'

<Media
    files={[
        {
            type: 'image',
            // ...
        },
        {
            type: 'video',
            // ...
        }
    ]}
/>

Image props

Video props

<Media
    files={[
        {
            type: 'image',
            file: 'https://path-to-image.png',
            title: 'a big cat'
        },
        {
            type: 'video',
            file: 'https://path-to-video.mp4',
            duration: 10
        }
    ]}
/>

Location

Send a location.

<Location latitude={60.734539} longitude={77.608548}  />

latitude

Latitude coordinate.

required

number

longitude

Longitude coordinate.

required

number

livePeriodSeconds

A period when a location can be updated online.

required

number

<Location livePeriodSeconds={60 * 30} />

title

buttons

isNewMessageEveryRender

simulateTyping

parseMode

disableNotification

replyToMessageId

personaId

forceReply

Poll

Send a poll.

<Poll question="Do you like Urban Bot?">
    <Option>Yes</Option>
    <Option>Of course</Option>
    <Option>Сertainly</Option>
</Poll>

children

required

Option | Option[]

question

required

string

<Poll question="Do you like Urban Bot?">...</Poll>

withMultipleAnswers

optional

boolean

<Poll withMultipleAnswers>...</Poll>

isAnonymous

optional

boolean

<Poll isAnonymous>...</Poll>

rightOption

If it is a quiz you can set a right answer.

optional

string | number

<Poll rightOption={1}>...</Poll>

explanation

If it is a quiz you can set an explanation of right answer.

optional

string

<Poll explanation="2 + 2 = 4">...</Poll>

livePeriodSeconds

A period when a poll can be active.

optional

number

<Poll livePeriodSeconds={60 * 30}>...</Poll>

type

optional

string

<Poll type="quiz">...</Poll>

title

buttons

isNewMessageEveryRender

simulateTyping

parseMode

disableNotification

replyToMessageId

personaId

forceReply

Option

Piece of Poll.

<Option>Yes</Option>

children

required

string

id

The unique id. If you don't specify it, it is generated automatically.

optional

string

<Option id="some-id">Yes</Option>

Contact

Send a contact.

<Contact firstName="Kamola" phoneNumber="+71234567890" />;

phoneNumber

optional

string | number

<Contact phoneNumber="+71234567890" />

username

optional

string

<Contact username="ledamint" />

firstName

optional

string

<Contact firstName="Vanya" />

lastName

optional

string

<Contact lastName="Che Guevara" />

vCard

optional

string

title

buttons

isNewMessageEveryRender

simulateTyping

parseMode

disableNotification

replyToMessageId

personaId

forceReply

Notification

Use it for sending a message every n time.

<Notification intervalSeconds={2}>
    <Text>Ping every two second</Text>
</Notification>

children

Any component(s) from urban-bot.

required

ReactNode | ReactNode[]

intervalSeconds

Message sends one time in intervalSeconds. First time is after intervalSeconds.

required

number

← Todo ListHooks →