> ## Documentation Index > Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt > Use this file to discover all available pages before exploring further. # Send your agent a message > Sends your personal agent a message, which it takes as one turn of its conversation, waking it first if it is asleep and waiting first for an update under way to finish: the call returns once it is awake, the message pending. Read your messages for its reply once the turn ends. Refused (409 agent_message_pending) while an earlier message is pending, (409 agent_host_illegal_transition) while your agent is paused, pausing, resuming, being set up or deleted, or lost, and answers 504 agent_host_wake_failed when it did not wake in time; a message whose wake did not report in stays pending until the next wake. ## OpenAPI ````yaml api-reference/openapi.account.json POST /agent/messages openapi: 3.1.0 info: title: Aether Account & Integrations API version: 0.1.0 description: >- Account, billing, and integration-management endpoints used by the Aether web app and CLI. Root-mounted; NOT part of the versioned /v1 contract. servers: - url: https://api.runaether.dev security: - bearerAuth: [] paths: /agent/messages: post: tags: - agent summary: Send your agent a message description: >- Sends your personal agent a message, which it takes as one turn of its conversation, waking it first if it is asleep and waiting first for an update under way to finish: the call returns once it is awake, the message pending. Read your messages for its reply once the turn ends. Refused (409 agent_message_pending) while an earlier message is pending, (409 agent_host_illegal_transition) while your agent is paused, pausing, resuming, being set up or deleted, or lost, and answers 504 agent_host_wake_failed when it did not wake in time; a message whose wake did not report in stays pending until the next wake. operationId: sendAgentMessage requestBody: content: application/json: schema: additionalProperties: false properties: text: description: >- What to tell your agent: not blank, at most 16384 characters (Unicode code points). maxLength: 16384 minLength: 1 type: string x-aether-string-length-unit: unicode-code-point required: - text type: object required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/AgentOwnerMessage' description: Created '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/OrgAuthorizationErrorResponse' description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not Found '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Conflict '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error '504': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Gateway Timeout components: schemas: AgentOwnerMessage: additionalProperties: false properties: cause: description: >- Who sent the message: web, you, from the web app; inbound_text, you, by text from your verified phone; operator, Aether. enum: - operator - web - inbound_text type: string completed_at: description: When the turn ended, or the message failed; absent while pending. format: date-time type: string direction: enum: - owner type: string id: format: uuid type: string issued_at: format: date-time type: string pictures: description: >- The pictures you texted with the message, by the https URLs your messaging provider hosts them at, in the order sent; empty for none. items: type: string type: array reply: description: >- What your agent said in the turn, as Aether holds it: cut to 4096 characters (the whole reply stays in your agent's conversation). Present on a completed message whose agent said something. type: string state: description: >- pending: your agent has not finished the turn, or has not woken for it yet; completed: the turn ended; failed: your agent could not take the message. enum: - pending - completed - failed type: string text: description: The message your agent was sent. type: string texted_reply: $ref: '#/components/schemas/AgentTextedReply' turn_started_at: description: >- When your agent took the message, when Aether recorded it: present on a completed message, but for one completed before Aether recorded turn starts. format: date-time type: string required: - id - direction - text - pictures - state - cause - issued_at type: object ErrorResponse: additionalProperties: false properties: code: type: string error: minLength: 1 type: string errors: items: $ref: '#/components/schemas/ErrorDetail' type: array required: - error type: object OrgAuthorizationErrorResponse: additionalProperties: false properties: code: enum: - org_membership_required - org_role_insufficient - org_suspended - account_deleting type: string error: minLength: 1 type: string required: - error - code type: object AgentTextedReply: additionalProperties: false properties: carries: description: >- reply: your agent's reply; run_out: your balance had run out, so the text said so and where to top up; failure: your agent could not answer, so the text said so and that your message is kept here. enum: - reply - run_out - failure type: string sms: $ref: '#/components/schemas/AgentMessageSMS' required: - carries - sms type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object AgentMessageSMS: oneOf: - $ref: '#/components/schemas/AgentSMSPlain' - $ref: '#/components/schemas/AgentSMSUndelivered' - $ref: '#/components/schemas/AgentSMSFailed' - $ref: '#/components/schemas/AgentSMSRefused' AgentSMSPlain: additionalProperties: false properties: outcome: description: >- none: the text is on its way to the messaging provider; sent: the provider accepted it, and no carrier refused it since; sms_opted_out: it was not sent, your phone texted STOP, and texting START resumes texts. enum: - none - sent - sms_opted_out type: string required: - outcome type: object AgentSMSUndelivered: additionalProperties: false properties: outcome: description: >- undelivered: the provider accepted the text and the carrier did not deliver it. enum: - undelivered type: string reason: description: The provider's or carrier's reason, as it gave it. type: string required: - outcome type: object AgentSMSFailed: additionalProperties: false properties: outcome: description: >- failed: the provider refused the text, or it could not be sent; indeterminate: it was sent and the provider's answer was lost, so it may have arrived. enum: - failed - indeterminate type: string reason: description: The provider's or carrier's reason, as it gave it. type: string required: - outcome - reason type: object AgentSMSRefused: additionalProperties: false properties: outcome: description: 'refused: the text was not sent, for refusal.' enum: - refused type: string refusal: description: >- Why the text was not sent: phone_unverified, you have no verified phone; balance_insufficient, your balance ran out; cap_reached, your agent sent its daily limit of texts. enum: - phone_unverified - balance_insufficient - cap_reached type: string required: - outcome - refusal type: object securitySchemes: bearerAuth: bearerFormat: JWT scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.