Payloads

A message's fields travel as protobuf values, and scripts work with JavaScript values. Asterobot converts them both ways: when a script reads traffic.payload, and when it builds a payload for send(), request() or an interceptor's { payload }. The two directions aren't symmetric, and this page lists every rule.

The Dofus protocol reference gives the type of each field.

Types at a glance

Field names

Payloads always read with camelCase names: the field sender_name reads as senderName. When sending, both spellings work, so { ticketKey: session.gameToken } and { ticket_key: session.gameToken } set the same field. Give each field only once: the same field under both spellings is an error, even with the same value.

Every key of the object you send must be a field of the message. An unknown key is an error, not something Asterobot skips.

Present, absent and zero

When reading

• Plain fields are always there. A field the server didn't set reads as its zero value: "", 0, 0n, false, an empty array or object, or for an enum, its first value, such as "GLOBAL" for a chat channel.
• Fields marked optional in the protocol reference, and fields that hold a message, are only there when they're set. In ChatChannelMessageEvent, for example, originServerId only appears on lines from the cross-server community channels.
• In a oneof, only the member that's set is there.

A field is never null, and never present with the value undefined. An absent field reads as undefined because it isn't there, so read fields with ?., and give defaults with ??:

// No originServerId means the line was said on this server.
const server = traffic.payload?.originServerId ?? session.serverId;

For plain fields, a zero value and an unset field look the same: a 0 may have been sent as 0, or not sent at all.

When sending

• Leave a field out to leave it unset. A plain field then arrives as its zero value.
• undefined as a value is refused, even though the field would be left out anyway. Watch for variables that can be undefined, and only add the fields you have a value for.
• null is accepted only for a field that holds a message, and leaves it unset. On any other field, it's refused.

const payload = { channel: "PARTY", content: text };
// A metadata key set to undefined would be refused.
if (metadata) payload.metadata = metadata;

await send("ChatChannelMessageRequest", payload);

Numbers and BigInt

64-bit fields read as BigInt values, whatever their size:

const id = traffic.payload?.senderCharacterId; // for example 123456789012n

if (id === 123456789012n) {
  // A BigInt equals another BigInt, never a number.
}

When sending, a 64-bit field takes a BigInt, a decimal string, or a number that's a safe integer. A bigger number is refused, because a JavaScript number can't hold it exactly.

32-bit fields work the other way: they read as numbers and refuse BigInt values. Convert with Number() before putting a BigInt in a 32-bit field. The JavaScript you need covers BigInt itself.

Enums

An enum field reads as the name of its value, such as "GUILD". When sending, give the name or the value's number. Names are case-sensitive: "guild" is refused.

A value Asterobot has no name for reads as its number. Some enum values still have scrambled names, which can change: don't rely on those.

Lists

A repeated field reads as an array and takes an array. Each item follows the rules of the field's type, and an error in an item gives its position after the field name, such as [2].

Maps

A map field reads as a plain object. Its keys are always strings, even when the map's keys are numbers or booleans: the key 12 reads as "12", and true as "true". When sending, give an object with keys written the same way. An error in an entry gives its key after the field name, such as ["12"].

Nested messages

A field that holds another message reads as an object with that message's fields, which follow the same rules, and takes an object when sending. Errors give the whole path, from the message name down to the field, separated by dots.

Oneofs

A oneof is a group of fields of which at most one is set. ChatPrivateMessageRequest has one called target: a private message goes to a character, with name, or to an account, with tag.

• When reading, only the member that's set is in the payload.
• When sending, set one member. Setting two is an error, and the editor marks it too.

await send("ChatPrivateMessageRequest", { name: "Airelle", content: "On my way" });

Errors

A payload that doesn't fit its message makes send() and request() reject, before anything is sent. In an interceptor's { payload }, the same error shows on the bot's console after build replacement payload for and the message name, and the original message continues. The Network tool's Send a game message checks payloads its own way, with different texts: see Send messages by hand.

Every error starts with the path to the problem: the message name, then the fields as you wrote them, with list positions and map keys.

The other field types give these texts after the field's path:

Next, Sessions covers what a script knows about its game connection, and Error messages lists every error text a script can meet.