> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ocpplab.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ocpplab.io/_mcp/server.

# Send a raw OCPP proxy message

POST https://api.ocpplab.io/evcharger/commands/proxy-message
Content-Type: application/json

Send one raw OCPP message, as written, from the targeted virtual chargers to their CSMS. Use it for actions that have no dedicated endpoint. Returns 202 once the command is queued. Each `results[].command.id` is a command id: poll `GET /evcharger/commands/{command_id}` (`client.evcharger.commands.get_status(command_id)`) until its status is final. It answers 404 until the charger has received the command.

Reference: https://docs.ocpplab.io/api-reference/evcharger/commands/proxy-message

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Body (application/json)

This endpoint expects an OcppProxyMessageRequest.

- `target` (CommandTarget, required) — Command target resolved in the service layer under the caller organization.
- `payload` (ProxyMessagePayload, required) — Raw OCPP proxy message payload for one charger.

## Response

### 202

Command queued for the targeted chargers

- `targeted_count` (integer, required)
- `queued_count` (integer, required)
- `failed_count` (integer, required)
- `results` (list of LocationQueuedCommandResult, required)
- `failed` (list of LocationCommandFailure, required)

## Errors

### 400 Bad Request Error

Invalid command target

- `detail` (string, required) — Human-readable error message returned by the API.

### 401 Unauthorized Error

Missing or invalid Bearer token

- `detail` (string, required) — Human-readable error message returned by the API.

### 404 Not Found Error

Charger not found

- `detail` (string, required) — Human-readable error message returned by the API.

### 422 Unprocessable Entity Error

Validation Error

- `detail` (list of ValidationError, optional) — One entry per invalid field.

### 500 Internal Server Error

Internal server error

- `detail` (string, required) — Human-readable error message returned by the API.

### 503 Service Unavailable Error

MQTT producer is not started

- `detail` (string, required) — Human-readable error message returned by the API.

## Types

### CommandTarget

Command target resolved in the service layer under the caller organization.

- `deployment_id` (string, optional, nullable) — One deployment or charger id to command. Mutually exclusive with location_id.
- `identity` (string, optional, nullable) — One charger identity to command. Mutually exclusive with location_id.
- `location_id` (string, optional, nullable) — Command all resolved chargers in this location.
- `charger_ids` (list of string, optional, nullable) — Optional narrowed deployment ids when targeting a location.

### ProxyMessagePayload

Raw OCPP proxy message payload for one charger.

- `action` (string, required)
- `payload` (map from string to any, optional)

### LocationQueuedCommandResult

One queued command result item for a location-scoped command request.

- `charger_id` (string, required)
- `identity` (string, required)
- `command` (QueuedCommandResponse, required) — Queued command payload returned by simulator action endpoints.

### LocationCommandFailure

Failed charger result returned by location command endpoints.

- `error` (string, required)
- `identity` (string, optional, nullable)

### ValidationError

Why one field is invalid.

- `loc` (list of ValidationErrorLocItems, required) — Where the field is: ``body`` / ``query`` / ``path`` / ``header``, then its name.
- `msg` (string, required) — What is wrong, in English.
- `type` (string, required) — Machine-readable error code, e.g. ``missing``.
- `input` (any, optional) — The value that was sent.
- `ctx` (ValidationErrorCtx, optional) — Details of the rule that failed, e.g. `{"le": 200}`.

### QueuedCommandResponse

Queued command payload returned by simulator action endpoints.

- `id` (string, required)
- `event_type` (string, required)
- `ocpp_version` (string, required)
- `payload` (map from string to any, required) — Command payload sent to the simulator queue.

### ValidationErrorLocItems

### ValidationErrorCtx

Details of the rule that failed, e.g. `{"le": 200}`.

## Examples

**Request**

```json
{
  "target": {
    "deployment_id": "vd-cp-fast-201"
  },
  "payload": {
    "action": "TriggerMessage"
  }
}
```

**Response**

```json
{
  "targeted_count": 2,
  "queued_count": 2,
  "failed_count": 0,
  "results": [
    {
      "charger_id": "dep-123",
      "identity": "CP-TEST-001",
      "command": {
        "id": "a1b2c3d4e5f6",
        "event_type": "start_transaction",
        "ocpp_version": "ocpp1.6",
        "payload": {
          "id_tag": "TAG-RFID-001",
          "evse_id": 1,
          "connector_id": 1
        }
      }
    }
  ],
  "failed": []
}
```

**SDK Code**

```python evcharger_commands_proxy_message_example
import requests

url = "https://api.ocpplab.io/evcharger/commands/proxy-message"

payload = {
    "target": { "deployment_id": "vd-cp-fast-201" },
    "payload": { "action": "TriggerMessage" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript evcharger_commands_proxy_message_example
const url = 'https://api.ocpplab.io/evcharger/commands/proxy-message';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"target":{"deployment_id":"vd-cp-fast-201"},"payload":{"action":"TriggerMessage"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go evcharger_commands_proxy_message_example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ocpplab.io/evcharger/commands/proxy-message"

	payload := strings.NewReader("{\n  \"target\": {\n    \"deployment_id\": \"vd-cp-fast-201\"\n  },\n  \"payload\": {\n    \"action\": \"TriggerMessage\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby evcharger_commands_proxy_message_example
require 'uri'
require 'net/http'

url = URI("https://api.ocpplab.io/evcharger/commands/proxy-message")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"target\": {\n    \"deployment_id\": \"vd-cp-fast-201\"\n  },\n  \"payload\": {\n    \"action\": \"TriggerMessage\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java evcharger_commands_proxy_message_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.ocpplab.io/evcharger/commands/proxy-message")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"target\": {\n    \"deployment_id\": \"vd-cp-fast-201\"\n  },\n  \"payload\": {\n    \"action\": \"TriggerMessage\"\n  }\n}")
  .asString();
```

```php evcharger_commands_proxy_message_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.ocpplab.io/evcharger/commands/proxy-message', [
  'body' => '{
  "target": {
    "deployment_id": "vd-cp-fast-201"
  },
  "payload": {
    "action": "TriggerMessage"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp evcharger_commands_proxy_message_example
using RestSharp;

var client = new RestClient("https://api.ocpplab.io/evcharger/commands/proxy-message");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"target\": {\n    \"deployment_id\": \"vd-cp-fast-201\"\n  },\n  \"payload\": {\n    \"action\": \"TriggerMessage\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift evcharger_commands_proxy_message_example
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "target": ["deployment_id": "vd-cp-fast-201"],
  "payload": ["action": "TriggerMessage"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.ocpplab.io/evcharger/commands/proxy-message")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```