How to Create an Activity from an Application
Scope:
crmPermissions are checked for the CRM item linked to the activity:
- crm.activity.add and crm.activity.update — permission to modify the item
- crm.activity.delete — permission to delete the item
Choose a tool for developing with an AI agent:
- use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
- use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation
An installed application can add an activity to the timeline of a CRM card.
When an employee opens it, Bitrix24 displays the application page in the side panel. This way you can work with the application directly from the card: view linked data, perform the required actions, or address an external service.
How the Scenario Works
Three participants are involved in the scenario: the user, Bitrix24, and the application:
- the user — selects a CRM item and works with the created activity in the timeline
- Bitrix24 — retains the activity and passes its opening parameters to the application page
- the application — creates, updates, or deletes the activity through the REST API
First, the user selects a CRM item on the application page — a lead in this scenario. The application creates an activity for it using the crm.activity.add method. The activity appears in the timeline of the lead.
When the user clicks this activity, Bitrix24 opens the application page and passes the activity identifier in PLACEMENT_OPTIONS. This is how the application knows which activity to work with and can update or delete it.
The scenario uses the following methods:
- crm.activity.add — creates the application activity
- crm.activity.update — updates or completes the activity
- crm.activity.delete — deletes the activity
Next, build the application page step by step: prepare the file, determine the opening mode, add the interface, and set up the work with the activity. To call REST methods and interface functions, use the BX24.js JavaScript library.
1. Prepare the Application
Create an application with the crm scope and prepare a server accessible from the external network.
Create the index.php file on the server. In the following steps, add the code blocks to it one after another. After the last step, you will have a complete application page.
2. Determine the Opening Mode
The same application page can be opened in two situations:
- the user launches the application in Bitrix24 — on the page, the user selects a lead and creates an activity for it
- the user clicks the created activity in the timeline of the lead — Bitrix24 opens the same page with actions to complete or delete the activity
To determine the situation, the application checks the parameters passed by Bitrix24. When an activity is opened from the timeline, Bitrix24 passes PLACEMENT_OPTIONS in a POST request. The value contains a JSON string with two parameters:
action— the action the page is opened with. For an application activity, the value isview_activityactivity_id— the numeric identifier of the opened activity. Pass it to the crm.activity.update or crm.activity.delete methods
Add the code that retrieves and checks these parameters to the beginning of the index.php file:
How to Use Examples in Documentation
<?php
header('Content-Type: text/html; charset=UTF-8');
$placementOptions = [];
if (!empty($_POST['PLACEMENT_OPTIONS']))
{
$decodedOptions = json_decode($_POST['PLACEMENT_OPTIONS'], true);
if (is_array($decodedOptions))
{
$placementOptions = $decodedOptions;
}
}
$activityId = isset($placementOptions['activity_id'])
? (int)$placementOptions['activity_id']
: 0;
$isActivityView = ($placementOptions['action'] ?? '') === 'view_activity'
&& $activityId > 0;
?>
If the page is opened from an activity, the $isActivityView variable receives the value true, and $activityId receives the numeric identifier of the activity.
3. Add the Page Interface
Right after the PHP block, add the HTML markup. It displays the required buttons depending on the value of $isActivityView:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Application activity</title>
</head>
<body hidden>
<script src="//api.bitrix24.com/api/v1/"></script>
<?php if ($isActivityView): ?>
<p>Activity identifier: <?= $activityId ?></p>
<button type="button" onclick="updateActivity(<?= $activityId ?>)">
Complete activity
</button>
<button type="button" onclick="deleteActivity(<?= $activityId ?>)">
Delete activity
</button>
<?php else: ?>
<button type="button" onclick="selectCRMEntity()">Select lead</button>
<span id="selected-entity">Lead not selected</span>
<button type="button" onclick="addActivity()">Create activity</button>
<?php endif; ?>
<p id="status" role="status"></p>
When the user launches the application in Bitrix24, the page displays buttons for selecting a lead and creating an activity. When the user opens the created activity from the timeline, the page displays its identifier and the actions to complete or delete it.
4. Initialize BX24.js
After the HTML markup, add the shared variables and helper functions. Replace the value of responsibleId with the identifier of the employee responsible for the activity.
The BX24.js library is already included in the previous block. Wait for it to initialize using BX24.init before calling Bitrix24 methods.
<script>
const responsibleId = 1;
let selectedEntityId = null;
BX24.init(() => {
document.body.hidden = false;
});
function showStatus(message, isError = false)
{
const status = document.getElementById('status');
status.textContent = message;
status.style.color = isError ? 'red' : 'green';
}
function showError(result)
{
showStatus(
`Error: ${result.error()} — ${result.error_description()}`,
true
);
}
</script>
After BX24.init runs, the page becomes visible. The showStatus and showError functions display the result of the REST calls.
5. Add Activity Creation
To create an application activity, call the crm.activity.add method with the PROVIDER_ID=REST_APP field. An activity with PROVIDER_ID=REST_APP can be created only from an installed application. It can be updated or deleted only by the application that created it.
When called through a webhook, Bitrix24 returns the error Application context required., and when called from another application — Access denied.
The crm.activity.add method is marked as deprecated, but in this scenario it cannot be replaced with crm.activity.todo.add: that method does not accept the PROVIDER_ID field.
In the example, the user selects a lead through BX24.selectCRM. For a lead, the function returns an identifier with a prefix, for example L_123. The application removes the L_ prefix and passes the numeric part to OWNER_ID of the crm.activity.add method.
For a different CRM object, change entityType, the identifier prefix, and OWNER_TYPE_ID.
The main fields for creating an activity:
Required parameters are marked with *
OWNER_TYPE_ID*— the numeric identifier of the CRM object type. For a lead, pass1OWNER_ID*— the numeric identifier of the selected leadPROVIDER_ID*— the provider identifier. For an application activity, passREST_APPPROVIDER_TYPE_ID— the type of the application activity. If the field is not passed, Bitrix24 uses the valueLINKSUBJECT*— the name of the activity in the timelineRESPONSIBLE_ID*— the identifier of the employee responsible for the activity
The TYPE_ID field is normally required for crm.activity.add. For REST_APP, it can be omitted: the method automatically sets the activity type to "Provider".
After the previous block, add the functions for selecting a lead and creating an activity:
<script>
function selectCRMEntity()
{
BX24.selectCRM(
{ entityType: ['lead'] },
(selected) => {
const lead = selected.lead && selected.lead[0];
if (!lead)
{
return;
}
const id = Number(lead.id.replace(/^L_/, ''));
if (!Number.isInteger(id) || id <= 0)
{
showStatus('Failed to determine the lead identifier', true);
return;
}
selectedEntityId = id;
document.getElementById('selected-entity').textContent = lead.title;
showStatus(`Selected the lead with identifier ${id}`);
}
);
}
function addActivity()
{
if (!selectedEntityId)
{
showStatus('Select a lead first', true);
return;
}
BX24.callMethod(
'crm.activity.add',
{
fields: {
OWNER_TYPE_ID: 1,
OWNER_ID: selectedEntityId,
PROVIDER_ID: 'REST_APP',
PROVIDER_TYPE_ID: 'LINK',
SUBJECT: 'New application activity',
COMPLETED: 'N',
RESPONSIBLE_ID: responsibleId,
DESCRIPTION: 'Description of the new activity'
}
},
(result) => {
if (result.error())
{
showError(result);
return;
}
showStatus(`Activity created. Identifier: ${result.data()}`);
}
);
}
</script>
After a successful call to crm.activity.add, the page displays the numeric identifier of the created activity.
6. Add Activity Update and Deletion
To complete an activity, pass its identifier to the crm.activity.update method and set the COMPLETED=Y field.
To delete an activity, pass the same identifier to the crm.activity.delete method.
Add the following block after the activity creation functions. It also closes the body and html elements, so place it at the end of the file:
<script>
function updateActivity(id)
{
BX24.callMethod(
'crm.activity.update',
{
id,
fields: {
COMPLETED: 'Y',
SUBJECT: 'Activity completed',
DESCRIPTION: 'Description of the completed activity'
}
},
(result) => {
if (result.error())
{
showError(result);
return;
}
showStatus('Activity updated');
}
);
}
function deleteActivity(id)
{
if (!window.confirm('Delete the activity?'))
{
return;
}
BX24.callMethod(
'crm.activity.delete',
{ id },
(result) => {
if (result.error())
{
showError(result);
return;
}
showStatus('Activity deleted');
}
);
}
</script>
</body>
</html>
The methods return true after the activity is successfully updated or deleted. The page displays a message about the completed action.
7. Deploy and Check the Application
Save index.php and place it on a server accessible from the external network. Specify the resulting URL as the address of the main page of the application, then install the application in Bitrix24.
Check the scenario:
- Open the application, select a lead, and create an activity
- Check that the application displayed the numeric identifier of the new activity
- Open the card of the selected lead and find the activity in the timeline
- Click the activity and check that Bitrix24 opened the application with the same identifier
- Complete or delete the activity and check the result in the timeline