> ## 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.json POST /agent/messages openapi: 3.1.0 info: title: Aether API version: 0.1.0 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/AgentErrorResponse' description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/AgentErrorResponse' description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/OrgAuthorizationErrorResponse' description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/AgentErrorResponse' description: Not Found '409': content: application/json: schema: $ref: '#/components/schemas/AgentErrorResponse' description: Conflict '422': content: application/json: schema: $ref: '#/components/schemas/AgentErrorResponse' description: Unprocessable Entity '500': content: application/json: schema: $ref: '#/components/schemas/AgentErrorResponse' description: Internal Server Error '504': content: application/json: schema: $ref: '#/components/schemas/AgentErrorResponse' 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 20000 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 AgentErrorResponse: additionalProperties: false properties: code: enum: - account_deleting - aether_inference_unavailable - aether_inference_unserved - agent_connector_not_found - agent_credential_unreadable - agent_default_project_archived - agent_event_not_found - agent_host_account_deleting - agent_host_command_not_found - agent_host_creation_disabled - agent_host_exists - agent_host_illegal_transition - agent_host_not_allowlisted - agent_host_not_found - agent_host_not_ready - agent_host_other_provider_app - agent_host_project_not_eligible - agent_host_provisioning_failed - agent_host_state_changed - agent_host_wake_failed - agent_line_unavailable - agent_link_code_picked_up - agent_link_expired - agent_link_invalid_code - agent_link_needs_web_session - agent_link_no_verified_phone - agent_link_not_found - agent_link_other_account - agent_link_takes_a_code - agent_link_takes_no_code - agent_link_used - agent_message_not_found - agent_message_pending - agent_not_found - bad_gateway - bad_request - conflict - connection_account_held - connection_agent_only - connection_harness_mismatch - connection_is_default - connection_kind_not_runnable - connection_name_taken - connection_not_found - connection_not_held - connection_not_of_agent_family - connection_option_mismatch - connection_runs_agent - connection_runs_profiles - control_forbidden - default_skill_required - forbidden - gateway_timeout - github_auth_check_unavailable - github_claim_unverified - github_identity_mismatch - github_reconnect_required - github_ref_not_found - gone - integration_auth_unexpected - integration_not_in_directory - integration_shape_changed - internal_error - line_exists - line_not_found - line_not_imessage - mcp_connection_github_not_connected - mcp_connection_oauth_not_accepted - mcp_connection_org_not_offered - mcp_connection_secret_invalid - mcp_connection_server_changed - mcp_connection_static_secret_not_accepted - mcp_credential_policy_not_applicable - mcp_credential_policy_org_unavailable - mcp_credential_policy_required - mcp_oauth_app_auth_method_unsupported - mcp_oauth_app_invalid - mcp_oauth_app_issuer_invalid - mcp_oauth_app_required - mcp_oauth_not_advertised - mcp_oauth_pkce_unsupported - mcp_oauth_registration_failed - mcp_repo_config_invalid - mcp_server_address_refused - mcp_server_aether_managed - mcp_server_api_key_not_applicable - mcp_server_args_invalid - mcp_server_auth_discovery_failed - mcp_server_auth_unsupported - mcp_server_directory_managed - mcp_server_directory_moved - mcp_server_display_name_invalid - mcp_server_env_invalid - mcp_server_headers_invalid - mcp_server_key_invalid - mcp_server_key_reserved - mcp_server_key_taken - mcp_server_kind_change_refused - mcp_server_not_from_directory - mcp_server_not_mcp - mcp_server_package_invalid - mcp_server_plugin_bundled - mcp_server_plugin_off - mcp_server_response_too_large - mcp_server_return_to_invalid - mcp_server_runtime_invalid - mcp_server_switched_off - mcp_server_unreachable - mcp_server_url_invalid - mcp_server_version_unpinned - method_not_allowed - model_not_on_aether_inference - no_dispatch_target - not_acceptable - not_an_agent_host - not_found - not_implemented - org_role_insufficient - org_suspended - payment_required - plugin_moved - plugin_name_taken - plugin_request_invalid - plugin_server_key_reserved - plugin_server_key_taken - plugin_server_probe_failed - plugin_server_required - plugin_skill_invalid - plugin_source_address_refused - plugin_source_empty - plugin_source_invalid - plugin_source_not_found - plugin_source_not_public - plugin_source_too_large - plugin_source_unreachable - plugin_source_unsupported - plugin_switched_off - plugin_undeliverable - precondition_failed - rate_limited - repository_not_reachable - request_canceled - request_timeout - request_too_large - service_unavailable - skill_slug_reserved - unauthenticated - unsupported_media_type - validation_failed - whatsapp_not_enabled minLength: 1 type: string error: minLength: 1 type: string errors: items: $ref: '#/components/schemas/ErrorDetail' type: array required: - error - code type: object OrgAuthorizationErrorResponse: additionalProperties: false properties: code: enum: - org_membership_required - org_role_insufficient - org_suspended - account_deleting - agent_host_route_not_allowed - credential_kind_not_admitted 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; daily_cap: your agent had spent its daily cap, so the text said so, that it rests until midnight your time, and where to raise it; plan_window: your Claude plan's usage window was spent, so the text said until when; provider_down: your agent's model provider refused or was down, so the text said to text again in a few minutes; failure: your agent could not answer, so the text said so and that your message is kept here. enum: - reply - run_out - failure - daily_cap - plan_window - provider_down 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 rail: description: 'The rail the text went over: imessage, whatsapp or sms.' enum: - sms - whatsapp - imessage type: string whatsapp_skip: description: >- Why the text went over SMS instead of WhatsApp: not_ready, the line's WhatsApp was not ready; rate_limited, WhatsApp's caps or three unanswered messages; whatsapp_limited, WhatsApp limited the line; whatsapp_unavailable, WhatsApp sending was paused; not_connected, WhatsApp was not connected on the line. enum: - not_ready - rate_limited - whatsapp_limited - whatsapp_unavailable - not_connected 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 rail: description: 'The rail the text went over: imessage, whatsapp or sms.' enum: - sms - whatsapp - imessage type: string reason: description: The provider's or carrier's reason, as it gave it. type: string whatsapp_skip: description: >- Why the text went over SMS instead of WhatsApp: not_ready, the line's WhatsApp was not ready; rate_limited, WhatsApp's caps or three unanswered messages; whatsapp_limited, WhatsApp limited the line; whatsapp_unavailable, WhatsApp sending was paused; not_connected, WhatsApp was not connected on the line. enum: - not_ready - rate_limited - whatsapp_limited - whatsapp_unavailable - not_connected 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 rail: description: 'The rail the text went over: imessage, whatsapp or sms.' enum: - sms - whatsapp - imessage type: string reason: description: The provider's or carrier's reason, as it gave it. type: string whatsapp_skip: description: >- Why the text went over SMS instead of WhatsApp: not_ready, the line's WhatsApp was not ready; rate_limited, WhatsApp's caps or three unanswered messages; whatsapp_limited, WhatsApp limited the line; whatsapp_unavailable, WhatsApp sending was paused; not_connected, WhatsApp was not connected on the line. enum: - not_ready - rate_limited - whatsapp_limited - whatsapp_unavailable - not_connected 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, recorded while the agent's texts were capped per day, which they no longer are. 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.