Send message

POST

messaging

{session}

messages

send

Send message

curl --request POST \
  --url https://api.polymorfa.com/messaging/{session}/messages/send \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "conversation": {
    "phoneNumber": "+15550001111"
  },
  "content": {
    "text": "Hello"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({conversation: {phoneNumber: '+15550001111'}, content: {text: 'Hello'}})
};

fetch('https://api.polymorfa.com/messaging/{session}/messages/send', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.polymorfa.com/messaging/{session}/messages/send"

payload = {
    "conversation": { "phoneNumber": "+15550001111" },
    "content": { "text": "Hello" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

package main

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

func main() {

	url := "https://api.polymorfa.com/messaging/{session}/messages/send"

	payload := strings.NewReader("{\n  \"conversation\": {\n    \"phoneNumber\": \"+15550001111\"\n  },\n  \"content\": {\n    \"text\": \"Hello\"\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(string(body))

}

{
  "success": true,
  "data": {
    "id": "739182640518203",
    "whatsapp_ids": {
      "linked_devices": "<string>",
      "official_api": "<string>"
    },
    "conversation": {
      "id": "739182640518203",
      "phoneNumber": "<string>",
      "bsuid": "<string>",
      "username": "<string>"
    },
    "timestamp": "2023-11-07T05:31:56Z",
    "status": "<string>",
    "type": "<string>",
    "content": {
      "text": "<string>"
    },
    "whatsapp_id": "<string>",
    "mediaId": "<string>"
  }
}

{
  "success": true,
  "data": {
    "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "conflict_error",
    "code": "idempotency_conflict",
    "message": "This Idempotency-Key was already used with a different request. Use a new key for a different request.",
    "param": null
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#idempotency-conflict"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

Authorizations

Authorization

string

header

required

Polymorfa organization key (pmfa_ prefix), project token (pmfa_pt_ prefix) where supported, or short-lived client token (pmfa_ct_ prefix). Organization and project keys may be personal or service-account owned and enforce selected action scopes. Organization keys cover the team and its projects; project tokens stay inside one project. Client tokens stay inside their live project and session and enforce their client rules.

Headers

Idempotency-Key

string

Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 24 hours. A retry with the same key, credential, Polymorfa-Version, and request never runs the write again: it returns 409 idempotency_completed when the original succeeded, or the original server error, with Idempotent-Replayed: true. Reusing the key for a different request returns 409 idempotency_conflict; a retry while the original is still running returns 409 idempotency_in_progress, and a retry after an unrecorded outcome returns 409 idempotency_outcome_unknown.

Value constraints

Constraint	Accepted input
String length	`1` through `255` characters

Required string length: 1 - 255

Path Parameters

session

string

required

Identifier of the connected Polymorfa session.

Body

application/json

Specify conversation and content containing exactly one message kind. Shared options remain outside content.

conversation

object

required

Public conversation identifier or E.164 phone number.

Accepted alternatives

Alternative	Accepted input
Alternative 1	Required fields: `id`
Alternative 2	Required fields: `phoneNumber`
Alternative 3	Required fields: `bsuid`

Option 1
Option 2
Option 3

Show child attributes

content

object

required

Specifies content for this native send message request.

Accepted alternatives

Alternative	Accepted input
Alternative 1	Type: `object`; Required fields: `text`
Alternative 2	Type: `object`; Required fields: `image`
Alternative 3	Type: `object`; Required fields: `video`
Alternative 4	Type: `object`; Required fields: `file`
Alternative 5	Type: `object`; Required fields: `voice`
Alternative 6	Type: `object`; Required fields: `location`
Alternative 7	Type: `object`; Required fields: `poll`
Alternative 8	Type: `object`; Required fields: `contact`
Alternative 9	Type: `object`; Required fields: `requestPhoneNumber`
Alternative 10	Type: `object`; Required fields: `product`
Alternative 11	Type: `object`; Required fields: `productList`
Alternative 12	Type: `object`; Required fields: `order`
Alternative 13	Type: `object`; Required fields: `list`
Alternative 14	Type: `object`; Required fields: `buttons`
Alternative 15	Type: `object`; Required fields: `addressMessage`
Alternative 16	Type: `object`; Required fields: `flow`
Alternative 17	Type: `object`; Required fields: `callPermissionRequest`
Alternative 18	Type: `object`; Required fields: `template`

Show child attributes

isForwarded

boolean

Mark this message as forwarded.

mentions

string[]

User IDs to mention in this message.

Value constraints

Constraint	Accepted input
Item pattern	`^[1-9][0-9]{0,18}$`

Opaque Polymorfa resource ID. Keep this value as a string.

Pattern: ^[1-9][0-9]{0,18}$

quotedMessage

object

Specifies quoted message for this native send message request.

Show child attributes

Response

Message sent successfully

success

enum<boolean>

required

Whether the request succeeded.

Allowed values

Value	Meaning
`true`	True.

Available options:

true

data

object

required

Structured data carried by this object.

Show child attributes

Send message

curl --request POST \
  --url https://api.polymorfa.com/messaging/{session}/messages/send \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "conversation": {
    "phoneNumber": "+15550001111"
  },
  "content": {
    "text": "Hello"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({conversation: {phoneNumber: '+15550001111'}, content: {text: 'Hello'}})
};

fetch('https://api.polymorfa.com/messaging/{session}/messages/send', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.polymorfa.com/messaging/{session}/messages/send"

payload = {
    "conversation": { "phoneNumber": "+15550001111" },
    "content": { "text": "Hello" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

package main

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

func main() {

	url := "https://api.polymorfa.com/messaging/{session}/messages/send"

	payload := strings.NewReader("{\n  \"conversation\": {\n    \"phoneNumber\": \"+15550001111\"\n  },\n  \"content\": {\n    \"text\": \"Hello\"\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(string(body))

}

{
  "success": true,
  "data": {
    "id": "739182640518203",
    "whatsapp_ids": {
      "linked_devices": "<string>",
      "official_api": "<string>"
    },
    "conversation": {
      "id": "739182640518203",
      "phoneNumber": "<string>",
      "bsuid": "<string>",
      "username": "<string>"
    },
    "timestamp": "2023-11-07T05:31:56Z",
    "status": "<string>",
    "type": "<string>",
    "content": {
      "text": "<string>"
    },
    "whatsapp_id": "<string>",
    "mediaId": "<string>"
  }
}

{
  "success": true,
  "data": {
    "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "conflict_error",
    "code": "idempotency_conflict",
    "message": "This Idempotency-Key was already used with a different request. Use a new key for a different request.",
    "param": null
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#idempotency-conflict"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "request_log_url": "<string>"
  },
  "data": null,
  "docs": "<string>"
}

Overview

Messaging API

Platform API

Graph API

Webhook events

Authorizations

Headers

Path Parameters

Body

Response