Skip to main content

​
Telnyx Group Messaging

Group Messaging builds upon the MMS (Multimedia Messaging Service) protocol in order to facilitate multi-party conversations. Building upon the shortcomings of existing platforms, Group Messaging presents a breakthrough approach to Group MMS that puts emphasis on ease of use, rigorous compliance, and unbeatable pricing. The API reference can be found here.

​
Sending a group message

Here’s an example of how to send a group message. Request - 
curl -X POST -H 'Content-Type: application/json' \
  --header "Authorization: Bearer ***" \
  -d '{"from": "+13125790427", "to": ["+18655551234", "+13125551234"], "text": "Greetings from Telnyx!", "media_urls": ["http://placekitten.com/320/240"]}' \
  https://api.telnyx.com/v2/messages/group_mms
Response - 
{
    "data": {
        "record_type": "message",
        "direction": "outbound",
        "id": "403188fd-58c5-4557-a8de-1700a358d768",
        "type": "MMS",
        "organization_id": "2cdddce5-daaa-4515-9fb2-995cc429d82c",
        "messaging_profile_id": "1e0df9c5-8716-4bcf-8fb2-9f6d9527fd95",
        "from": "+12024494776",
        "to": [
            {
                "phone_number": "+13475636849",
                "status": "queued",
                "carrier": "NEW CINGULAR WIRELESS PCS, LLC - DC",
                "line_type": "Wireless"
            },
            {
                "phone_number": "+13122708269",
                "status": "queued",
                "carrier": "TELNYX LLC",
                "line_type": "Pre-Paid Wireless"
            },
            {
                "phone_number": "+17084769340",
                "status": "queued",
                "carrier": "T-MOBILE USA, INC.",
                "line_type": "Wireless"
            },
            {
                "phone_number": "+13122708074",
                "status": "queued",
                "carrier": "TELNYX LLC",
                "line_type": "Pre-Paid Wireless"
            }
        ],
        "text": "Greetings from Telnyx!",
        "media": [
            {
                "url": "http://placekitten.com/320/240",
                "content_type": null,
                "sha256": null,
                "size": null
            }
        ],
        "webhook_url": "https://webhook.site/b1a0a3a7-0771-40e8-9b11-e175b7f0b633",
        "webhook_failover_url": "",
        "encoding": "GSM-7",
        "parts": 1,
        "tags": [],
        "cost": {
            "amount": "0.1200",
            "currency": "USD"
        },
        "received_at": "2023-06-27T14:53:53.376+00:00",
        "sent_at": null,
        "completed_at": null,
        "valid_until": "2023-06-27T15:53:53.376+00:00",
        "errors": []
    }
}
Delivery Status Webhook - 
{
  "data": {
    "event_type": "message.finalized",
    "id": "b40653f5-91cd-46b1-9542-0c092bd29795",
    "occurred_at": "2023-08-08T10:29:36.090+00:00",
    "payload": {
      "cc": [],
      "completed_at": "2023-08-08T10:29:36.090+00:00",
      "cost": {
        "amount": "0.0400",
        "currency": "USD"
      },
      "direction": "outbound",
      "encoding": "GSM-7",
      "errors": [],
      "from": {
        "carrier": "Telnyx",
        "line_type": "Wireless",
        "phone_number": "+12024494776"
      },
      "group_message_id": "403189d4-b1d6-4993-b263-6470e5224430",
      "id": "403189d4-b1d6-4993-b263-6470e5224430",
      "media": [
        {
          "content_type": null,
          "sha256": null,
          "size": null,
          "url": "http://placekitten.com/320/240"
        }
      ],
      "messaging_profile_id": "1e0df9c5-8716-4bcf-8fb2-9f6d9527fd95",
      "organization_id": "2cdddce5-daaa-4515-9fb2-995cc429d82c",
      "parts": 1,
      "received_at": "2023-08-08T10:29:31.939+00:00",
      "record_type": "message",
      "sent_at": "2023-08-08T10:29:32.751+00:00",
      "tags": [],
      "text": "hello world - this is a test",
      "to": [
        {
          "carrier": "CELLCO PARTNERSHIP DBA VERIZON WIRELESS - IL",
          "line_type": "Wireless",
          "phone_number": "+16186635052",
          "status": "delivered"
        },
        {
          "carrier": "CELLCO PARTNERSHIP DBA VERIZON WIRELESS - FL",
          "line_type": "Wireless",
          "phone_number": "+13056479132",
          "status": "delivered"
        }
      ],
      "type": "MMS",
      "valid_until": "2023-08-08T11:29:31.939+00:00",
      "webhook_failover_url": "",
      "webhook_url": "https://webhook.site/82977c82-3ef0-4139-83f1-2a5446708f90"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://webhook.site/82977c82-3ef0-4139-83f1-2a5446708f90"
  }
}

​
Receiving a group message

Here’s an example of what an inbound message webhook would look like in a group messaging conversation Webhook - 
{
  "data": {
    "event_type": "message.received",
    "id": "0d7c4fbe-d075-435f-b71b-694391743967",
    "occurred_at": "2023-08-08T13:03:05.129+00:00",
    "payload": {
      "autoresponse_type": null,
      "cc": [
        "+13122708269",
        "+17084769340",
        "+13122708074",
        "+12024494776"
      ],
      "completed_at": null,
      "cost": null,
      "direction": "inbound",
      "encoding": "UCS-2",
      "errors": [],
      "from": {
        "carrier": "AT&T",
        "line_type": "Wireless",
        "phone_number": "+13475636849"
      },
      "id": "9d12c9d0-5172-429a-8fb9-cc9da297717f",
      "is_spam": false,
      "media": [],
      "messaging_profile_id": "1e0df9c5-8716-4bcf-8fb2-9f6d9527fd95",
      "organization_id": "2cdddce5-daaa-4515-9fb2-995cc429d82c",
      "parts": 1,
      "received_at": "2023-08-08T13:03:04.812+00:00",
      "record_type": "message",
      "sent_at": null,
      "subject": "",
      "tags": [],
      "text": "Checking in on the Telnyx team",
      "to": [
        {
          "carrier": "Telnyx",
          "line_type": "Wireless",
          "phone_number": "+12024494776",
          "status": "webhook_delivered"
        },
        {
          "carrier": "TELNYX LLC",
          "line_type": "Pre-Paid Wireless",
          "phone_number": "+13122708269",
          "status": "unknown"
        },
        {
          "carrier": "T-MOBILE USA, INC.",
          "line_type": "Wireless",
          "phone_number": "+17084769340",
          "status": "unknown"
        },
        {
          "carrier": "TELNYX LLC",
          "line_type": "Pre-Paid Wireless",
          "phone_number": "+13122708074",
          "status": "unknown"
        }
      ],
      "type": "MMS",
      "valid_until": null,
      "webhook_failover_url": "https://webhook.site/ccfcbfd0-9e63-45de-bac9-14f7b5968ca1",
      "webhook_url": "https://webhook.site/82977c82-3ef0-4139-83f1-2a5446708f90"
    },
    "record_type": "event"
  },
  "meta": {
    "attempt": 1,
    "delivered_to": "https://webhook.site/82977c82-3ef0-4139-83f1-2a5446708f90"
  }
}

​
Webhook / Detail record behaviour

  • You should receive an individual webhook status update for each recipient following the v2 schema.
  • Handset delivery status is not available for Non-Telnyx receipients within in a conversation. Their status will be marked as unknown.
  • We cut individual message detail records per receipient in a group message via our portal / reporting API’s.
  • An additional attribute called group_message_id is returned to allow users to correlate each individual record to the overarching group message conversation. This is returned via API response, webhooks and is also available via detailed records.

​
What caveats should I be aware of with this feature?

  • Group Messaging takes place over the MMS protocol and supports a maximum of 8 recipients in a conversation.
  • Limitations of the MMS protocol apply here.
  • This feature is only available via our v2 API. Please ensure you have a v2 webhook version selected on your messaging profile to ensure you receive inbound messages.
  • Group messaging is charged per recipient. Standard MMS rates and corresponding carrier passthrough fees apply here.
  • Only US / CAN destinations are supported.