Get Started

// 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()

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
}

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

// 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
}

// 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
}

// 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'
  }
})

// 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 }
})

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()!