Adding messages

In an AsyncAPI document, adding messages mainly means setting up channels and operations. This is key for explaining how data moves between your applications. However, sometimes you might just want to use the AsyncAPI document to describe the messages themselves, without anything else.

Add messages

In an AsyncAPI document, you define message definitions under channels. However, the best practice is to first define these messages under the 'components' section as reusable definitions. That way, you can reference them easily from a channel.

Here is a diagram showing some channel fields and the relation between channel messages and components messages:

Channels section

Define the channels section in your AsyncAPI document, including the messages your channel accepts. For example:

1channels:
2  allCommentsLiked:
3    address: comment/liked
4    messages:
5      commentLiked:
6        description: Message that is being sent when a comment has been liked by someone.
7        payload:
8           type: object
9           title: commentLikedPayload
10           additionalProperties: false
11           properties:
12               commentId: 
13                 type: string
14                 description: Id of the comment that was liked
15    description: Notification channel for all the services that need to know comment is liked.

The above example presents an application that communicates over the allCommentsLiked channel, which only accepts one message called commentLiked.

messages section

In your AsyncAPI document, create a components.messages section to define each message your application uses as a reusable message. When setting up multiple channels, you won't have to repeat the same message definitions. For example:

1components:
2  messages:
3    commentLiked:
4        description: Message that is being sent when a comment has been liked by someone.
5        payload:
6           type: object
7           title: commentLikedPayload
8           additionalProperties: false
9           properties:
10               commentId: 
11                 type: string
12                 description: Id of the comment that was liked

You can reuse messages using the Reference Object. For example:

1    messages:
2      commentLiked:
3        $ref: '#/components/messages/commentLiked'

Here's the complete AsyncAPI document with channels reusing the same message:

1asyncapi: 3.0.0
2info:
3  title: Example API
4  version: '1.0.0'
5channels:
6  allCommentsLiked:
7    address: comment/liked
8    messages:
9      commentLiked:
10        $ref: '#/components/messages/commentLikedUnliked'
11    description: Notification channel for all the services that need to know comment is liked.
12  allCommentUnliked:
13    address: comment/unliked
14    messages:
15      commentUnliked:
16        $ref: '#/components/messages/commentLikedUnliked'
17    description: Notification channel for all the services that need to know comment is liked.
18components:
19  messages:
20    commentLikedUnliked:
21        description: Message that is being sent when a comment has been liked or unliked by someone.
22        payload:
23           type: object
24           title: commentInfoPayload
25           additionalProperties: false
26           properties:
27               commentId: 
28                 type: string
29                 description: Id of the comment that was liked or unliked

Identifier of the message

The key name that represents a message in your AsyncAPI document must be interpreted as messageId. If your document defines channels, the message key defined in the channel is the messageId.

1channels:
2  allCommentsLiked:
3    address: comment/liked
4    messages:
5      commentLiked:
6        $ref: '#/components/messages/commentLikedUnliked'
7    description: Notification channel for all the services that need to know comment is liked.

The above example shows a commentLiked message under the allCommentsLiked channel. It references a reusable message definition from the components section represented by the commentLikedUnliked key. In this setup, the commentLiked key is the messageId and not commentLikedUnliked.

Messages under operations

Operations specify which channels they interact with. If a channel has several messages, but your operation only involves one, indicate which specific message the operation uses.

1channels:
2  allComments:
3    address: comments
4    messages:
5      commentLiked:
6        $ref: '#/components/messages/commentLikedMsg'
7      commentUnliked:
8        $ref: '#/components/messages/commentUnlikedMsg'
9    description: Notification channel for all the services that need to know comment is liked.
10operations:
11  onCommentLiked:
12    action: receive
13    channel:
14      $ref: '#/channels/allComments'
15    messages:
16      - $ref: '#/channels/allComments/messages/commentLiked'

The above example demonstrates how to specify the message for the onCommentsLiked operation received from the allCommentLiked channel. It's important to note that the message reference points to the channel, not the components section. That ensures accurate information about the messageId, which in this case is commentLiked, not commentLikedMsg.