Soracom Beam

UDP → HTTP/HTTPS Entry Point

This entry point accepts UDP traffic from an Air for Cellular device, encodes the content using Base64, and forwards the data to the forwarding destination as an HTTP request via HTTP or HTTPS, using strictly one UDP datagram per request.

Versions

When using the Beam UDP → HTTP/HTTPS entry point, you may select between version 201509 and 202411. The differences between these versions are as follows.

Unified Endpoint Behavior

The Unified Endpoint behavior does not change based on the Platform Version selected for the UDP → HTTP/HTTPS entry point. If Unified Endpoint's Response Format is set to Soracom Beam, it will always operate based on Platform Version 202411.

The same behavior applies when the Response Format of Unified Endpoint is set to Auto (default) and only Soracom Beam is enabled in the group settings.

Error Responses

If the destination server returns an HTTP status code of 400 or higher, the TCP → HTTP/HTTPS entry point considers it an error response. In such cases, the response is transmitted to the device as the payload of a TCP packet, formatted according to the specifications defined by the platform version. As opposed to platform version 201509, platform version 202411 adds the the body of the HTTP response and removes the forwarding URL from the error response.

Platform Version Default Error Response Format
202411 ${HTTP status code} ${HTTP response body returned by the destination server}
201509 ${HTTP status code} ${destination URL} returns a status code (${HTTP status code}). Please check your destination.\r\n

Configuration

Entry Point

Your device should be configured to send UDP traffic to: beam.soracom.io:23080.

Parameters

For details on configuring and using header manipulations, refer to the Header Manipulation page.

Behavior

Request Behavior

Beam will encode the original message using Base64, and set the encoded content as the body of an HTTP POST request using JSON format.

{"payload": "<Base64-encoded-message>"}

Beam will also set the user agent string as SORACOM Beam in the HTTP request header.

Since the maximum transmission data size per message conforms to the maximum size of the UDP fragment, it is 65,536 bytes including the header.

Response Behavior

Since UDP has no request and response mechanism like HTTP, Beam will return a UDP packet to the device containing the HTTP response code and message received from the forwarding destination. The UDP packet message will use the following format: ${http-status-code} ${http-response-body}

When receiving the HTTP response code is not required, you can enable the Skip status code option in order to reduce data usage.

Example

Response example without body

echo "test message" | nc -v -u beam.soracom.io 23080
>found 0 associations
>found 1 connections:
>     1:    flags=82<CONNECTED,PREFERRED>
>  outif (null)
>  src 192.168.43.232 port 61852
>  dst 100.127.127.100 port 23080
>  rank info not available
>
>Connection to beam.soracom.io port 23080 [udp/*] succeeded!
>
>200

Response example with a body

echo "bad message" | nc -v -u beam.soracom.io 23080
>found 0 associations
>found 1 connections:
>     1:    flags=82<CONNECTED,PREFERRED>
>  outif (null)
>  src 192.168.43.232 port 61852
>  dst 100.127.127.100 port 23080
>  rank info not available
>
>Connection to beam.soracom.io port 23080 [udp/*] succeeded!
>
>400 Message from server

Advanced Configuration

The UDP → HTTP/HTTPS entry point can also be configured through the Soracom API or CLI by using the SoracomBeam namespace.

Configuration should be performed using udp://beam.soracom.io:23080 as the configuration key value.

Parameters

Sample

[
  {
    "key":"udp://beam.soracom.io:23080",
    "value": {
      "name": "udp2https",
      "destination": "https://beamtest.soracom.io/",
      "version": "202411",
      "enabled": true,
      "addSubscriberHeader": true,
      "addSignature": true,
      "psk": "topsecret",
      "customHeaders": {
        "X-GROUP-NAME": {
          "action": "append",
          "headerKey": "X-GROUP-NAME",
          "headerValue": "TEST"
        }
      }
    }
  }
]