Actions

The ballerinax/asb package exposes the following clients:

Client	Purpose
`Message Sender`	Send individual, batch, and scheduled messages to Azure Service Bus queues and topics.
`Message Receiver`	Receive messages from queues and subscriptions, settle messages, and manage locks.
`Administrator`	Manage Azure Service Bus entities: create, get, update, delete, and list queues, topics, subscriptions, and rules.

For event-driven integration, see the Trigger Reference.

Message sender

Send individual, batch, and scheduled messages to Azure Service Bus queues and topics.

Configuration

Field	Type	Default	Description
`connectionString`	`string`	Required	The Azure Service Bus connection string.
`entityType`	`QUEUE	TOPIC`	Required
`topicOrQueueName`	`string`	Required	The name of the queue or topic.
`amqpRetryOptions`	`AmqpRetryOptions`	`()`	Retry options for AMQP operations (maxRetries, delay, maxDelay, tryTimeout, retryMode).

Initializing the client

import ballerinax/asb;

configurable string connectionString = ?;

asb:MessageSender sender = check new ({
    connectionString: connectionString,
    entityType: asb:QUEUE,
    topicOrQueueName: "my-queue"
});

Operations

Send messages

send

Sends a single message to the configured queue or topic.

Parameters:

Name	Type	Required	Description
`message`	`asb:Message`	Yes	The message to send, including `body`, optional `contentType`, `messageId`, `sessionId`, `timeToLive`, and application properties.

Returns: error?

Sample code:

check sender->send({
    body: "Hello from Ballerina",
    contentType: asb:TEXT,
    applicationProperties: {"source": "ballerina"}
});

sendPayload

Sends a message with just the payload content to the configured queue or topic. The payload is stored in the message as a byte stream.

Parameters:

Name	Type	Required	Description
`payload`	`anydata`	Yes	The payload to send as the message body.

Returns: error?

Sample code:

check sender->sendPayload("Order processed successfully");

sendBatch

Sends a batch of messages to the configured queue or topic.

Parameters:

Name	Type	Required	Description
`messageBatch`	`asb:MessageBatch`	Yes	A batch of messages to send, containing an array of `asb:Message` records.

Returns: error?

Sample code:

check sender->sendBatch({
    messages: [
        {body: "Message 1", contentType: asb:TEXT},
        {body: "Message 2", contentType: asb:TEXT}
    ]
});

Scheduling

schedule

Schedules a message for future delivery at the specified time.

Parameters:

Name	Type	Required	Description
`message`	`asb:Message`	Yes	The message to schedule.
`scheduledEnqueueTime`	`time:Civil`	Yes	The UTC time at which the message should become available.

Returns: int|error

Sample code:

int sequenceNumber = check sender->schedule(
    {body: "Scheduled message", contentType: asb:TEXT},
    {year: 2026, month: 3, day: 13, hour: 10, minute: 0}
);

cancel

Cancels a previously scheduled message using its sequence number.

Parameters:

Name	Type	Required	Description
`sequenceNumber`	`int`	Yes	The sequence number returned by the `schedule` operation.

Returns: error?

Sample code:

check sender->cancel(sequenceNumber);

Connection

Closes the sender connection and releases resources.

No parameters.

Returns: error?

Sample code:

check sender->close();

Message receiver

Receive messages from queues and subscriptions, settle messages, and manage locks.

Configuration

Field	Type	Default	Description
`connectionString`	`string`	Required	The Azure Service Bus connection string.
`entityConfig`	`QueueConfig\|TopicSubsConfig`	Required	Entity configuration: either `{queueName: "..."}` for queues or `{topicName: "...", subscriptionName: "..."}` for topic subscriptions.
`receiveMode`	`PEEK_LOCK	RECEIVE_AND_DELETE`	`PEEK_LOCK`
`maxAutoLockRenewDuration`	`int`	`300`	Maximum duration (in seconds) to automatically renew the message lock.
`amqpRetryOptions`	`AmqpRetryOptions`	`()`	Retry options for AMQP operations.

Initializing the client

import ballerinax/asb;

configurable string connectionString = ?;

asb:MessageReceiver receiver = check new ({
    connectionString: connectionString,
    entityConfig: {
        queueName: "my-queue"
    },
    receiveMode: asb:PEEK_LOCK
});

Operations

Receive messages

receive

Receives a single message from the queue or subscription.

Parameters:

Name	Type	Required	Description
`serverWaitTime`	`int?`	No	Maximum wait time in seconds for a message to arrive. Defaults to `60`.
`deadLettered`	`boolean`	No	When `true`, receives from the dead-letter sub-queue instead of the main queue or subscription. Defaults to `false`.

Returns: asb:Message|error?

Returns () if no message arrives within serverWaitTime. Always assign to a nilable type.

Sample code:

asb:Message? message = check receiver->receive(serverWaitTime = 60);
if message is () {
    // No message available
    return;
}

receivePayload

Receives the message from the configured queue or subscription directly bound to the expected payload type.

Parameters:

Name	Type	Required	Description
`serverWaitTime`	`int?`	No	Maximum wait time in seconds for a message to arrive. Defaults to `60`.
`T`	`typedesc<anydata>`	No	The expected payload type.
`deadLettered`	`boolean`	No	When `true`, receives from the dead-letter sub-queue instead of the main queue or subscription. Defaults to `false`.

Returns: T|error

Sample code:

string payload = check receiver->receivePayload(serverWaitTime = 60);

receiveBatch

Receives a batch of messages from the queue or subscription.

Parameters:

Name	Type	Required	Description
`maxMessageCount`	`int`	Yes	Maximum number of messages to receive in the batch.
`serverWaitTime`	`int?`	No	Maximum wait time in seconds. Defaults to `()` (no wait).
`deadLettered`	`boolean`	No	When `true`, receives from the dead-letter sub-queue instead of the main queue or subscription. Defaults to `false`.

Returns: asb:MessageBatch|error?

Returns () if no messages are available. Always assign to a nilable type.

Sample code:

asb:MessageBatch? batch = check receiver->receiveBatch(maxMessageCount = 10);
if batch is () {
    // No messages available
    return;
}

Message settlement

complete

Completes a message, removing it from the queue. Used in PEEK_LOCK mode.

Parameters:

Name	Type	Required	Description
`message`	`asb:Message`	Yes	The message to complete.

Returns: error?

Sample code:

asb:Message? message = check receiver->receive(serverWaitTime = 60);
if message is () {
    return;
}
check receiver->complete(message);

abandon

Abandons a message, releasing the lock so it can be received again.

Parameters:

Name	Type	Required	Description
`message`	`asb:Message`	Yes	The message to abandon.

Returns: error?

Sample code:

check receiver->abandon(message);

deadLetter

Moves a message to the dead-letter sub-queue.

Parameters:

Name	Type	Required	Description
`message`	`asb:Message`	Yes	The message to dead-letter.
`deadLetterReason`	`string?`	No	The reason for dead-lettering.
`deadLetterErrorDescription`	`string?`	No	A description of the error that caused dead-lettering.

Returns: error?

Sample code:

check receiver->deadLetter(message,
    deadLetterReason = "ProcessingFailure",
    deadLetterErrorDescription = "Unable to parse message body"
);

defer

Defers a message so it can only be received by its sequence number later.

Parameters:

Name	Type	Required	Description
`message`	`asb:Message`	Yes	The message to defer.

Returns: int|error

The returned int is the sequence number of the deferred message. Pass it to receiveDeferred to retrieve the message later.

Sample code:

int sequenceNumber = check receiver->defer(message);
// Later, retrieve the deferred message:
asb:Message? deferred = check receiver->receiveDeferred(sequenceNumber);

receiveDeferred

Receives a previously deferred message by its sequence number.

Parameters:

Name	Type	Required	Description
`sequenceNumber`	`int`	Yes	The sequence number of the deferred message.

Returns: asb:Message|error?

Sample code:

asb:Message? deferredMsg = check receiver->receiveDeferred(sequenceNumber);

Lock management

renewLock

Renews the lock on a message in PEEK_LOCK mode to extend processing time.

Parameters:

Name	Type	Required	Description
`message`	`asb:Message`	Yes	The message whose lock should be renewed.

Returns: error?

Sample code:

check receiver->renewLock(message);

Connection

Closes the receiver connection and releases resources.

No parameters.

Returns: error?

Sample code:

check receiver->closeReceiver();

Administrator

Manage Azure Service Bus entities: create, get, update, delete, and list queues, topics, subscriptions, and rules.

Configuration

Field	Type	Default	Description
`connectionString`	`string`	Required	The Azure Service Bus connection string with Manage rights.

Initializing the client

import ballerinax/asb;

configurable string connectionString = ?;

asb:Administrator admin = check new ({
    connectionString: connectionString
});

Operations

Queue management

createQueue

Creates a new queue in the Azure Service Bus namespace.

Parameters:

Name	Type	Required	Description
`queueName`	`string`	Yes	The name of the queue to create.
`queueProperties`	`CreateQueueOptions?`	No	Optional properties such as max size, TTL, lock duration, and dead-lettering settings.

Returns: QueueProperties|error

Sample code:

asb:QueueProperties queue = check admin->createQueue("my-new-queue");

Sample response:

{"name": "my-new-queue", "status": "Active", "maxSizeInMegabytes": 1024}

getQueue

Retrieves the properties of an existing queue.

Parameters:

Name	Type	Required	Description
`queueName`	`string`	Yes	The name of the queue.

Returns: QueueProperties|error

Sample code:

asb:QueueProperties queue = check admin->getQueue("my-queue");

updateQueue

Updates the properties of an existing queue.

Parameters:

Name	Type	Required	Description
`queueProperties`	`QueueProperties`	Yes	The updated queue properties.

Returns: QueueProperties|error

Sample code:

asb:QueueProperties queue = check admin->getQueue("my-queue");
asb:QueueProperties updated = check admin->updateQueue({
    ...queue,
    maxDeliveryCount: 15
});

deleteQueue

Deletes a queue from the namespace.

Parameters:

Name	Type	Required	Description
`queueName`	`string`	Yes	The name of the queue to delete.

Returns: error?

Sample code:

check admin->deleteQueue("my-old-queue");

listQueues

Lists all queues in the Azure Service Bus namespace.

Parameters:

Name	Type	Required	Description

Returns: QueueProperties[]|error

Sample code:

asb:QueueProperties[] queues = check admin->listQueues();

queueExists

Checks whether a queue with the given name exists.

Parameters:

Name	Type	Required	Description
`queueName`	`string`	Yes	The name of the queue to check.

Returns: boolean|error

Sample code:

boolean exists = check admin->queueExists("my-queue");

Topic management

createTopic

Creates a new topic in the Azure Service Bus namespace.

Parameters:

Name	Type	Required	Description
`topicName`	`string`	Yes	The name of the topic to create.
`topicProperties`	`CreateTopicOptions?`	No	Optional properties such as max size, TTL, and duplicate detection.

Returns: TopicProperties|error

Sample code:

asb:TopicProperties topic = check admin->createTopic("my-new-topic");

Sample response:

{"name": "my-new-topic", "status": "Active", "maxSizeInMegabytes": 1024}

getTopic

Retrieves the properties of an existing topic.

Parameters:

Name	Type	Required	Description
`topicName`	`string`	Yes	The name of the topic.

Returns: TopicProperties|error

Sample code:

asb:TopicProperties topic = check admin->getTopic("my-topic");

updateTopic

Updates the properties of an existing topic.

Parameters:

Name	Type	Required	Description
`topicProperties`	`TopicProperties`	Yes	The updated topic properties.

Returns: TopicProperties|error

Sample code:

asb:TopicProperties topic = check admin->getTopic("my-topic");
asb:TopicProperties updated = check admin->updateTopic({
    ...topic,
    defaultMessageTimeToLive: 3600
});

deleteTopic

Deletes a topic from the namespace.

Parameters:

Name	Type	Required	Description
`topicName`	`string`	Yes	The name of the topic to delete.

Returns: error?

Sample code:

check admin->deleteTopic("my-old-topic");

listTopics

Lists all topics in the Azure Service Bus namespace.

Parameters:

Name	Type	Required	Description

Returns: TopicProperties[]|error

Sample code:

asb:TopicProperties[] topics = check admin->listTopics();

topicExists

Checks whether a topic with the given name exists.

Parameters:

Name	Type	Required	Description
`topicName`	`string`	Yes	The name of the topic to check.

Returns: boolean|error

Sample code:

boolean exists = check admin->topicExists("my-topic");

Subscription management

createSubscription

Creates a new subscription under a topic.

Parameters:

Name	Type	Required	Description
`topicName`	`string`	Yes	The name of the parent topic.
`subscriptionName`	`string`	Yes	The name of the subscription to create.
`subscriptionProperties`	`CreateSubscriptionOptions?`	No	Optional subscription properties.

Returns: SubscriptionProperties|error

Sample code:

asb:SubscriptionProperties sub = check admin->createSubscription("my-topic", "my-subscription");

Sample response:

{"subscriptionName": "my-subscription", "topicName": "my-topic", "status": "Active"}

getSubscription

Retrieves the properties of an existing subscription.

Parameters:

Name	Type	Required	Description
`topicName`	`string`	Yes	The name of the parent topic.
`subscriptionName`	`string`	Yes	The name of the subscription.

Returns: SubscriptionProperties|error

Sample code:

asb:SubscriptionProperties sub = check admin->getSubscription("my-topic", "my-subscription");

updateSubscription

Updates the properties of an existing subscription.

Parameters:

Name	Type	Required	Description
`topicName`	`string`	Yes	The name of the parent topic.
`subscriptionProperties`	`SubscriptionProperties`	Yes	The updated subscription properties.

Returns: SubscriptionProperties|error

Sample code:

asb:SubscriptionProperties sub = check admin->getSubscription("my-topic", "my-sub");
asb:SubscriptionProperties updated = check admin->updateSubscription("my-topic", {
    ...sub,
    maxDeliveryCount: 20
});

deleteSubscription

Deletes a subscription from a topic.

Parameters:

Name	Type	Required	Description
`topicName`	`string`	Yes	The name of the parent topic.
`subscriptionName`	`string`	Yes	The name of the subscription to delete.

Returns: error?

Sample code:

check admin->deleteSubscription("my-topic", "my-old-subscription");

listSubscriptions

Lists all subscriptions under a topic.

Parameters:

Name	Type	Required	Description
`topicName`	`string`	Yes	The name of the parent topic.

Returns: SubscriptionProperties[]|error

Sample code:

asb:SubscriptionProperties[] subs = check admin->listSubscriptions("my-topic");

subscriptionExists

Checks whether a subscription exists under a topic.

Parameters:

Name	Type	Required	Description
`topicName`	`string`	Yes	The name of the parent topic.
`subscriptionName`	`string`	Yes	The name of the subscription to check.

Returns: boolean|error

Sample code:

boolean exists = check admin->subscriptionExists("my-topic", "my-subscription");

Rule management

createRule

Creates a new rule under a topic subscription for message filtering.

Parameters:

Name	Type	Required	Description
`topicName`	`string`	Yes	The name of the parent topic.
`subscriptionName`	`string`	Yes	The name of the subscription.
`ruleName`	`string`	Yes	The name of the rule to create.
`ruleProperties`	`CreateRuleOptions?`	No	Optional rule options including filter and action.

Returns: RuleProperties|error

Sample code:

asb:RuleProperties rule = check admin->createRule("my-topic", "my-sub", "high-priority-filter");

getRule

Retrieves the properties of a rule.

Parameters:

Name	Type	Required	Description
`topicName`	`string`	Yes	The name of the parent topic.
`subscriptionName`	`string`	Yes	The name of the subscription.
`ruleName`	`string`	Yes	The name of the rule.

Returns: RuleProperties|error

Sample code:

asb:RuleProperties rule = check admin->getRule("my-topic", "my-sub", "my-rule");

updateRule

Updates the properties of an existing rule.

Parameters:

Name	Type	Required	Description
`topicName`	`string`	Yes	The name of the parent topic.
`subscriptionName`	`string`	Yes	The name of the subscription.
`ruleProperties`	`RuleProperties`	Yes	The updated rule properties.

Returns: RuleProperties|error

Sample code:

asb:RuleProperties rule = check admin->getRule("my-topic", "my-sub", "my-rule");
asb:RuleProperties updated = check admin->updateRule("my-topic", "my-sub", rule);

deleteRule

Deletes a rule from a subscription.

Parameters:

Name	Type	Required	Description
`topicName`	`string`	Yes	The name of the parent topic.
`subscriptionName`	`string`	Yes	The name of the subscription.
`ruleName`	`string`	Yes	The name of the rule to delete.

Returns: error?

Sample code:

check admin->deleteRule("my-topic", "my-sub", "old-rule");

listRules

Lists all rules under a topic subscription.

Parameters:

Name	Type	Required	Description
`topicName`	`string`	Yes	The name of the parent topic.
`subscriptionName`	`string`	Yes	The name of the subscription.

Returns: RuleProperties[]|error

Sample code:

asb:RuleProperties[] rules = check admin->listRules("my-topic", "my-sub");

What's next

Trigger Reference: event-driven integration using asb:Listener
Setup Guide: obtain the connection string required for all clients
Example: complete worked examples for sender, receiver, and trigger

Message sender​

Configuration​

Initializing the client​

Operations​

Send messages​

Scheduling​

Connection​

Message receiver​

Configuration​

Initializing the client​

Operations​

Receive messages​

Message settlement​

Lock management​

Connection​

Administrator​

Configuration​

Initializing the client​

Operations​

Queue management​

Topic management​

Subscription management​

Rule management​

What's next​

Message sender

Configuration

Initializing the client

Operations

Send messages

Scheduling

Connection

Message receiver

Configuration

Initializing the client

Operations

Receive messages

Message settlement

Lock management

Connection

Administrator

Configuration

Initializing the client

Operations

Queue management

Topic management

Subscription management

Rule management

What's next