VoIP.infoThe independent guide to business communications.
VoIP.info Guide

Asterisk PJSIP MessageSend: Request-URI, headers and delivery evidence

Build one SIP MESSAGE deliberately, keep its Request-URI separate from To and From identity, and prove the protocol response without treating handler acceptance as user receipt.

Reviewed 2026-10-14Current Asterisk MessageSend, MESSAGE, MESSAGE_DATA and res_pjsip documentation plus RFC 3428 reviewed October 14, 2026; the APIs have been documented since Asterisk 10.0.0 and the endpoint message_context option since 13.5.0, but installed modules, endpoint and contact state, URI construction, authentication, peer method support, SIP transaction result, endpoint display and user receipt remain deployment specific, and no PBX, module, endpoint, AoR, contact, dialplan, header, body, request, response, packet, device, user interface or message was inspected or testedAdvancedDocumentation based · not lab tested

Separate the message object from the transport action

Asterisk documents MESSAGE() as the read/write message object and MessageSend() as the application that hands its current body to a technology selected by the destination prefix. Set or inspect MESSAGE(body), MESSAGE(from) and MESSAGE(to) as content and logical identity; then treat the MessageSend() destination as the routing instruction. These are related inputs, not interchangeable strings.

Confirm the installed Asterisk release, loaded messaging and PJSIP modules, originating dialplan path and whether the object was created locally or inherited from an incoming message. Reusing an inbound object can also retain fields or custom data. Clear or copy only reviewed values rather than assuming a fresh blank envelope.

Resolve the PJSIP destination into one Request-URI

Every PJSIP form documented by MessageSend() begins with the pjsip: technology prefix, but the remainder can name an endpoint, endpoint and AoR, an endpoint plus explicit SIP URI, the default endpoint plus URI, or a dialstring-like PJSIP/user@endpoint form. Freeze the exact input and the resulting Request-URI. Endpoint, AoR, current contact and URI user are separate routing objects.

Do not infer routing from the To header. In the dialstring-like form, Asterisk replaces the user part of the endpoint contact URI. An endpoint label can select policy and transport while a contact supplies the network target. Inspect both the loaded configuration and current contact before changing DNS, authentication or message content.

Keep Request-URI, To and From precedence visible

MessageSend(destination,from,to) can override the From and To values already stored by MESSAGE(). The destination still constructs the Request-URI. Record the final Request-URI, To URI, From URI, endpoint, transport and outbound proxy separately because a provider or device can route on one field while authorizing or displaying another.

Use SIP or SIPS URIs that match the intended policy and avoid untrusted string concatenation. An accepted From header is not authenticated identity, and a SIPS URI or TLS hop is not body-level end-to-end confidentiality. Redact message bodies and personal identifiers from shared traces unless their exact value is necessary and authorized.

Route incoming MESSAGE requests through the intended context

For received PJSIP MESSAGE requests, current res_pjsip documentation says an endpoint message_context routes them to the named dialplan context; if it is absent, the endpoint context is used. That lookup is separate from an outbound MessageSend() destination. Prove endpoint identification, the loaded context, extension match and dialplan execution before blaming an outbound route.

MESSAGE() exposes the incoming source, recipient and UTF-8 body. MESSAGE_DATA() can read or write message-associated custom data, but an inbound value is not automatically a reviewed outbound header. Copy only an allowlisted field, preserve content type and authorization, and do not build an open relay.

Interpret MESSAGE_SEND_STATUS narrowly

Asterisk documents INVALID_PROTOCOL, INVALID_URI, SUCCESS and FAILURE in MESSAGE_SEND_STATUS. Its SUCCESS means the message was successfully passed to the protocol handler; the documentation explicitly says delivery is not necessarily guaranteed. Preserve the application return, emitted SIP request and final SIP response as three separate observations.

RFC 3428 adds later boundaries: 200 means the final user agent accepted the message, not that a person read it; 202 means a gateway or store-and-forward service accepted it without end-to-end delivery assurance. A timeout, 4xx, 5xx or 6xx needs the exact responsible hop and response rather than a generic delivered-or-failed label.

Bound body size, overlap and acceptance testing

RFC 3428 treats each pager-model MESSAGE as independent and says MESSAGE does not establish a dialog. It also limits out-of-dialog requests to 1300 bytes unless the sender positively knows the path avoids a congestion-unsafe hop or stays below the path MTU boundary. The RFC prohibits starting a new out-of-dialog MESSAGE transaction to the same URI while an earlier one remains pending.

Acceptance should prove the intended Request-URI, headers, body type and size, authentication, final response, endpoint presentation and any separate user-receipt mechanism. Do not describe SIP MESSAGE as carrier SMS, durable chat, encrypted content or guaranteed user delivery without independent evidence. No PBX, endpoint, request, response, packet, device interface or message was tested for this guide.

Asterisk dialplan — bounded outbound SIP MESSAGE
[message-out]
exten => send,1,Set(MESSAGE(body)=Maintenance window begins at 22:00 UTC)
 same => n,Set(MESSAGE(from)=sip:ops@example.invalid)
 same => n,MessageSend(pjsip:desk-201)
 same => n,NoOp(Message handler status: ${MESSAGE_SEND_STATUS})
 same => n,Return()

Sources & applicability

Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.

Examples require adaptation to your topology. No live PBX or hardware testing is claimed.

Continue your research

Hub

Asterisk

Understand the programmable PBX and follow the Asterisk 22 LTS documentation baseline.

Explore topic →
Guide · Asterisk 22 LTS

Asterisk PJSIP: understand the configuration objects

Connect endpoint behavior, authentication, contacts and transport without collapsing them into one account setting.

Read guide →
Guide · Asterisk Latest API PJSIP_DIAL_CONTACTS, Dial, PJSIP_AOR, PJSIP_CONTACT and AMI object documentation plus PJSIP configuration relationships reviewed October 12, 2026; the generated pages reported branch 23, but the installed Asterisk version, endpoint, AoRs, contacts, registration expiry, qualification, dialplan, SIP responses and call legs remain deployment-specific, and no PBX, endpoint, AoR, contact, registration, device, channel, request, response or call was inspected or tested

Asterisk PJSIP_DIAL_CONTACTS: dial every current AoR contact

Build a call-time PJSIP dial string from the intended endpoint and AoR while keeping contact inventory, qualification, outbound channels and the winning answer independently observable.

Read guide →
Guide · Asterisk Latest API branch 23 PJSIP_PARSE_URI, PJSIP_PARSE_URI_FROM, PJSIP_HEADER and FILTER documentation plus current Asterisk security guidance and RFC 3261 reviewed October 13, 2026; no Asterisk host, module, channel, header, variable, URI, parser result, endpoint, route, transport, DNS result, SIP message or call was inspected or tested

Asterisk PJSIP_PARSE_URI: extract SIP URI parts without inventing trust

Parse a bounded SIP URI into documented components while keeping header ownership, absent-value sentinels, authorization, DNS, transport selection and final routing independently observable.

Read guide →
Guide · Asterisk 22 LTS

Asterisk dialplan: contexts, patterns and loaded-call evidence

Build a restricted Asterisk 22 call path, then prove its context, match, priorities and runtime behavior separately.

Read guide →
Reference · SIP standards; extension support depends on both peers

SIP URI structure: identity, routing and parameters

Parse sip and sips addresses without assuming they behave like ordinary telephone numbers.

Read guide →
Guide · Wireshark 4.x / current upstream tool documentation; inspect installed versions

VoIP packet-capture methodology

Select interfaces, time windows and paired capture points that distinguish network loss from missing evidence.

Read guide →
Troubleshooting · Current Asterisk MessageSend, MESSAGE, MESSAGE_DATA and res_pjsip documentation plus RFC 3428 reviewed October 14, 2026; the APIs have been documented since Asterisk 10.0.0 and the endpoint message_context option since 13.5.0, but installed modules, endpoint and contact state, URI construction, authentication, peer method support, SIP transaction result, endpoint display and user receipt remain deployment specific, and no PBX, module, endpoint, AoR, contact, dialplan, header, body, request, response, packet, device, user interface or message was inspected or tested

Asterisk PJSIP MessageSend fails or uses the wrong URI

Trace one text message from the Asterisk message object through destination parsing, endpoint and contact selection, SIP request, response and endpoint presentation.

Read guide →