Messages

You can use the Messages API (opens in a new tab) when doing engagement campaigns where you would create a new conversation when sending the initial mobile-terminated (opens in a new tab) (MT) message.

Create

Inbound messages are automatically threaded if the channels and senders are configured for conversation threading.

To add outbound messages to a conversation, use this method to send a message (opens in a new tab) via any of the supported channels.

x-agent-id attribute

The x-agent-id attribute is added to the request HTTP header to provide an agent identifier to a message being sent. It is used when integrations authenticate with an API key and use the agent entity to assign messages.

The value is the agentId which is the agent entity primary key, and you can find it in the response to the agents endpoints.

It is not mandatory to add the x-agent-id attribute to every Create Message request in the HTTP header. The purpose of the parameter is to provide the agent identifier to messages when integrations authenticate with an API key.

The behavior is as follows:

1. Account uses agents and API to send messages - there might be a need to include the x-agent-id attribute in the HTTP header, based on the assignment status. Agent role validation takes place. Supervisors can send messages that are assigned to other agents.
2. Account does not use agents - keeps conversations as unassigned and omits the x-agent-id from the request header; the message is not attributed to any agent and passes through.

Conversation assignment status	No x-agent-id provided	x-agent-id =	x-agent-id =
Unassigned	OK (no-agents-used scenario)	Error	Error
Assigned to AGENT	Error	OK	OK
Assigned to SUPERVISOR	Error	Error	OK

If you do not use agents, leave conversations always unassigned. The Create Message request HTTP header must omit the x-agent-id parameter.

However, if you do use agents, your account must have at least 1 agent to send messages. Create an agent using the Create Agent API (opens in a new tab) (no agent license is required).

Keep the following in mind while using roles to create agents and manage message permissions:

• AGENT role can reply only to conversations assigned to them.
• SUPERVISOR role can reply to any conversation.

The Create Message request HTTP header must contain x-agent-id parameter with the corresponding agentId`` as an agent identifier.

Get

Use the Get messages method to obtain all messages exchanged in a conversation.