---
title: "Get Started"
description: "Quick start guide for working with the SDK for Bitrix24 REST API"
canonical_url: "https://bitrix24.github.io/b24jssdk/docs/getting-started"
last_updated: "2026-05-08"
---
# Get Started

> Quick start guide for working with the SDK for Bitrix24 REST API

> [!WARNING]
> We are still updating this page. Some data may be missing here — we will complete it shortly.

## Overview

The SDK for working with Bitrix24 REST API provides a unified interface for interacting with the Bitrix24 API from JavaScript/TypeScript applications. This page will help you quickly get started with the library.

## Choosing the Appropriate Class

Choose a class depending on your usage scenario:

| Scenario | Class | Description |
| --- | --- | --- |
| Application embedded in the Bitrix24 interface | `B24Frame` | Automatically available in an iframe, uses the current user's token |
| Standalone server application with webhook | `B24Hook` | Uses a permanent webhook token for server applications |
| Standalone server application with OAuth | `B24OAuth` | Uses OAuth 2.0 with token refresh capability |

### For Client Applications (B24Frame)

If you are developing an application that will run inside the Bitrix24 interface:

```ts
// In an application embedded in Bitrix24

let $b24: undefined | B24Frame

async function getCurrentUser() {
  if (!$b24) {
    return
  }
  try {
    const response = await B24Frame.actions.v2.call.make({
      method: 'user.current',
      requestId: 'get-current-user'
    })

    if (response.isSuccess) {
      const user = response.getData()
      console.log('Current user:', user)
      return user
    } else {
      console.error('Error:', response.getErrorMessages())
    }
  } catch (error) {
    console.error('Unexpected error:', error)
  }
}

// Example of getting a list of contacts
async function getContacts() {
  if (!$b24) {
    return
  }
  const response = await B24Frame.actions.v2.callList.make({
    method: 'crm.contact.list',
    params: {
      filter: { '>ID': 0 },
      select: ['ID', 'NAME', 'LAST_NAME', 'EMAIL']
    },
    idKey: 'ID',
    requestId: 'get-all-contacts'
  })

  if (response.isSuccess) {
    return response.getData()
  }
  return []
}

async init() {
  $b24 = await initializeB24Frame()
}

await init()
```

### For Server Applications with Webhook (B24Hook)

For server applications with permanent access via webhook:

```ts
import { B24Hook } from '@bitrix24/b24jssdk'

// 1. Get the webhook URL from Bitrix24:
//    - Go to Bitrix24
//    - Settings → Developers → Webhooks
//    - Create a new webhook with the required permissions
//    - Copy the URL in the format: https://your-domain.bitrix24.com/rest/1/your-token/

// 2. Initialize B24Hook
const $b24 = B24Hook.fromWebhookUrl('https://your-domain.bitrix24.com/rest/1/your-token/')

// 3. Use API methods
async function getCompany(companyId: number) {
  const response = await $b24.actions.v2.call.make({
    method: 'crm.company.get',
    params: { id: companyId },
    requestId: `get-company-${companyId}`
  })

  if (response.isSuccess) {
    return response.getData()
  } else {
    throw new Error(`Error getting company: ${response.getErrorMessages().join(', ')}`)
  }
}

// Example of bulk creating deals
async function createMultipleDeals(dealsData: Array<{title: string, opportunity: number}>) {
  const calls = dealsData.map((deal, index) => [
    'crm.deal.add',
    {
      fields: {
        TITLE: deal.title,
        OPPORTUNITY: deal.opportunity,
        CATEGORY_ID: 0
      }
    }
  ])

  const response = await $b24.actions.v2.batchByChunk.make({
    calls,
    options: {
      requestId: 'bulk-create-deals'
    }
  })

  return response
}
```

### For Server Applications with OAuth (B24OAuth)

For server applications with OAuth 2.0 authentication:

```ts
import { B24OAuth } from '@bitrix24/b24jssdk'

// 1. Register an application in Bitrix24:
//    - Go to Bitrix24
//    - Settings → Developers → Applications
//    - Create a new application
//    - Get the Client ID and Client Secret

// 2. Initialize B24OAuth
const $b24 = B24OAuth.fromConfig({
  domain: 'your-domain.bitrix24.com',
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  accessToken: 'current_access_token',
  refreshToken: 'refresh_token'
})

// 3. Use API methods
async function getTasks() {
  const response = await $b24.actions.v2.call.make({
    method: 'tasks.task.list',
    params: {
      filter: { '>ID': 0 },
      select: ['ID', 'TITLE', 'STATUS']
    },
    requestId: 'get-all-tasks'
  })

  return response
}

// B24OAuth automatically refreshes tokens when they expire
```

## First Steps with API

### Simple Connection Test

```typescript
// Test API availability
async function testConnection() {
  // For B24Hook or B24OAuth
  const $b24 = B24Hook.fromWebhookUrl('https://your-domain.bitrix24.com/rest/1/your-token/')
  
  // 1. Check availability
  const isHealthy = await $b24.tools.healthCheck.make({
    requestId: 'health-check'
  })
  
  if (!isHealthy) {
    console.error('API unavailable. Check the webhook and connection.')
    return
  }
  
  // 2. Measure speed
  const pingTime = await $b24.tools.ping.make({
    requestId: 'ping-test'
  })
  
  console.log(`API available, response time: ${pingTime}ms`)
  
  // 3. Get current user information
  const userResponse = await $b24.actions.v2.call.make({
    method: 'user.current',
    requestId: 'get-current-user'
  })
  
  if (userResponse.isSuccess) {
    console.log('Current user:', userResponse.getData())
  }
  
  return true
}
```

### Basic CRM Operations

```ts
// Create a contact
async function createContact(name: string, lastName: string, email: string) {
  const response = await $b24.actions.v2.call.make({
    method: 'crm.contact.add',
    params: {
      fields: {
        NAME: name,
        LAST_NAME: lastName,
        EMAIL: [{ VALUE: email, VALUE_TYPE: 'WORK' }]
      }
    },
    requestId: 'create-contact'
  })
  
  return response
}

// Get a list of contacts
async function getAllContacts() {
  const generator = $b24.actions.v2.fetchList.make({
    method: 'crm.contact.list',
    params: {
      select: ['ID', 'NAME', 'LAST_NAME', 'EMAIL'],
      order: { ID: 'ASC' }
    },
    idKey: 'ID',
    requestId: 'fetch-all-contacts'
  })
  
  const allContacts = []
  for await (const chunk of generator) {
    allContacts.push(...chunk)
    console.log(`Loaded ${chunk.length} contacts, total: ${allContacts.length}`)
  }
  
  return allContacts
}
```

### Examples of Using Main Methods

```ts
// 1. Single call (Call)
const singleItem = await $b24.actions.v2.call.make({
  method: 'crm.company.get',
  params: { id: 123 },
  requestId: 'single-call'
})

// 2. Get entire list (CallList)
const allItems = await $b24.actions.v2.callList.make({
  method: 'crm.company.list',
  params: {
    filter: { '>ID': 0 },
    select: ['ID', 'TITLE']
  },
  idKey: 'ID',
  requestId: 'get-all-companies'
})

// 3. Stream processing (FetchList)
const generator = $b24.actions.v2.fetchList.make({
  method: 'crm.deal.list',
  params: { select: ['ID', 'TITLE', 'OPPORTUNITY'] },
  idKey: 'ID',
  requestId: 'stream-deals'
})

for await (const chunk of generator) {
  // Process in batches of 50 elements
  processChunk(chunk)
}

// 4. Batch processing (Batch)
const batchResult = await $b24.actions.v2.batch.make({
  calls: [
    ['crm.company.get', { id: 1 }],
    ['crm.company.get', { id: 2 }],
    ['crm.company.get', { id: 3 }]
  ],
  options: {
    requestId: 'batch-get-companies'
  }
})

// 5. Bulk batch processing (BatchByChunk)
const commands = Array.from({ length: 150 }, (_, i) => [
  'crm.contact.add',
  { fields: { NAME: `Contact ${i + 1}` } }
])

const bulkResult = await $b24.actions.v2.batchByChunk.make({
  calls: commands,
  options: {
    requestId: 'bulk-create-contacts'
  }
})
```

## Tips for Beginners

### 1. Always Use requestId

```ts
// Good
await $b24.actions.v2.call.make({
  method: 'crm.contact.get',
  params: { id: 123 },
  requestId: `contact-${123}-${Date.now()}`
})

// Bad (without requestId it will be difficult to debug)
await $b24.actions.v2.call.make({
  method: 'crm.contact.get',
  params: { id: 123 }
})
```

### 2. Check Operation Results

```ts
const response = await $b24.actions.v2.call.make({
  method: 'some.method',
  params: { /* ... */ },
  requestId: 'my-request'
})

// Always check isSuccess
if (!response.isSuccess) {
  console.error('Error:', response.getErrorMessages())
  // Error handling
  return
}

// Only after successful check, work with the data
const data = response.getData()!
```

### 3. Choose the Right Method for Working with Lists

| Data Volume | Method | Why |
| --- | --- | --- |
| < 1000 records | `CallList` | Easy to use, all data at once |
| > 1000 records | `FetchList` | Memory efficient, stream processing |
| Selective data | `Call` + `Batch` | Only needed records, control over requests |

## Need Help?

- [Open an issue on GitHub](https://github.com/bitrix24/b24jssdk/issues)
- [View existing questions](https://github.com/bitrix24/b24jssdk/issues?q=is%3Aissue)
- [Official documentation](https://apidocs.bitrix24.com/)

---

**Tip**: Start with simple queries (e.g., `user.current`) to make sure the connection works correctly before moving on to complex operations with CRM or tasks.

## Sitemap

See the full [sitemap](/b24jssdk/sitemap.md) for all pages.