Receiving messages

Inbound messages

In this section, you can find sample messages of every inbound message type supported by the Channels API from Telegram. The code snippets in every subsection demonstrate how a Telegram message is converted into a Channels API message.

See the following pages to understand more about retrieving messages or message statuses

Text

{
  "id": "ab03213f-2cba-49ea-b77e-8abc8bd46844",
  "channelId": "f007c3cb-1663-5a56-8c91-486056fef49e",
  "sender": {
    "contact": {
      "id": "4fe9991c-7296-47be-b960-6d052123403a",
      "identifierKey": "telegram:7933779519",
      "identifierValue": "1033247360",
      "annotations": {
        "name": "Test user"
      }
    }
  },
  "receiver": {
    "connector": {
      "id": "2e63afb0-d4bf-4d2d-a664-0b6152aaab98",
      "identifierValue": "7933779519"
    }
  },
  "body": {
    "type": "text",
    "text": {
      "text": "Sample text message"
    }
  },
  "meta": {
    "extraInformation": {
      "ChatID": "1033247360"
    }
  },
  "reference": "",
  "parts": [
    {
      "platformReference": "telegram:7933779519:1033247360:182"
    }
  ],
  "status": "delivered",
  "reason": "",
  "direction": "incoming",
  "context": {},
  "chargeableUnits": 1,
  "lastStatusAt": "2024-10-04T12:31:45.44Z",
  "createdAt": "2024-10-04T12:31:45.298Z",
  "updatedAt": "2024-10-04T12:31:45.44Z",
  "batchId": null
}

Image

{
  "id": "adda0a98-0c9e-4303-bcc9-d2fa24e2c9fe",
  "channelId": "f007c3cb-1663-5a56-8c91-486056fef49e",
  "sender": {
    "contact": {
      "id": "4fe9991c-7296-47be-b960-6d052123403a",
      "identifierKey": "telegram:7933779519",
      "identifierValue": "1033247360",
      "annotations": {
        "name": "Test user"
      }
    }
  },
  "receiver": {
    "connector": {
      "id": "2e63afb0-d4bf-4d2d-a664-0b6152aaab98",
      "identifierValue": "7933779519"
    }
  },
  "body": {
    "type": "image",
    "image": {
      "images": [
        {
          "mediaUrl": "https://media.api.bird.one/workspaces/ed06c631-ca43-47cc-b4a7-a7e2b141b22e/messages/adda0a98-0c9e-4303-bcc9-d2fa24e2c9fe/media/b6aaf2ba-5b61-4802-bf5a-662f7c35a3fc"
        }
      ]
    }
  },
  "meta": {
    "extraInformation": {
      "ChatID": "1033247360"
    }
  },
  "reference": "",
  "parts": [
    {
      "platformReference": "telegram:7933779519:1033247360:180"
    }
  ],
  "status": "delivered",
  "reason": "",
  "direction": "incoming",
  "context": {},
  "chargeableUnits": 1,
  "lastStatusAt": "2024-10-04T12:30:41.545Z",
  "createdAt": "2024-10-04T12:30:41.394Z",
  "updatedAt": "2024-10-04T12:30:41.545Z",
  "batchId": null
}

File

{
    "id": "354e8de5-6017-499f-a767-b388d4a2e1bf",
    "channelId": "f007c3cb-1663-5a56-8c91-486056fef49e",
    "sender": {
        "contact": {
            "id": "4fe9991c-7296-47be-b960-6d052123403a",
            "identifierKey": "telegram:7933779519",
            "identifierValue": "1033247360",
            "annotations": {
                "name": "Test user"
            }
        }
    },
    "receiver": {
        "connector": {
            "id": "2e63afb0-d4bf-4d2d-a664-0b6152aaab98",
            "identifierValue": "7933779519"
        }
    },
    "body": {
        "type": "file",
        "file": {
            "files": [
                {
                    "contentType": "application/pdf",
                    "mediaUrl": "https://media.api.bird.one/workspaces/ed06c631-ca43-47cc-b4a7-a7e2b141b22e/messages/354e8de5-6017-499f-a767-b388d4a2e1bf/media/a35786b6-b0c9-4d79-aa81-6f1b00eaf095",
                    "altText": "Ticket.pdf",
                    "filename": "Ticket.pdf"
                }
            ]
        }
    },
    "meta": {
        "extraInformation": {
            "ChatID": "1033247360"
        }
    },
    "reference": "",
    "parts": [
        {
            "platformReference": "telegram:7933779519:1033247360:178"
        }
    ],
    "status": "delivered",
    "reason": "",
    "direction": "incoming",
    "context": {},
    "chargeableUnits": 1,
    "lastStatusAt": "2024-10-04T12:28:53.677Z",
    "createdAt": "2024-10-04T12:28:53.409Z",
    "updatedAt": "2024-10-04T12:28:53.677Z",
    "batchId": null
}

Location

{
    "id": "caad89a9-9ebe-4a5a-b15f-84b0a93738a8",
    "channelId": "f007c3cb-1663-5a56-8c91-486056fef49e",
    "sender": {
        "contact": {
            "id": "4fe9991c-7296-47be-b960-6d052123403a",
            "identifierKey": "telegram:7933779519",
            "identifierValue": "1033247360",
            "annotations": {
                "name": "Test user"
            }
        }
    },
    "receiver": {
        "connector": {
            "id": "2e63afb0-d4bf-4d2d-a664-0b6152aaab98",
            "identifierValue": "7933779519"
        }
    },
    "body": {
        "type": "location",
        "location": {
            "coordinates": {
                "latitude": 52.377486,
                "longitude": 4.901026
            },
            "location": {
                "address": "",
                "label": "52° 22' 38.95\" N, 4° 54' 3.69\" E"
            }
        }
    },
    "meta": {
        "extraInformation": {
            "ChatID": "1033247360"
        }
    },
    "reference": "",
    "parts": [
        {
            "platformReference": "telegram:7933779519:1033247360:176"
        }
    ],
    "status": "delivered",
    "reason": "",
    "direction": "incoming",
    "context": {},
    "chargeableUnits": 1,
    "lastStatusAt": "2024-10-04T12:27:09.437Z",
    "createdAt": "2024-10-04T12:27:09.269Z",
    "updatedAt": "2024-10-04T12:27:09.437Z",
    "batchId": null
}

Interactive message

Interactive message reply

{
    "id": "c686a354-2e0f-46c5-92a3-2174e2652f71",
    "channelId": "f007c3cb-1663-5a56-8c91-486056fef49e",
    "sender": {
        "contact": {
            "id": "4fe9991c-7296-47be-b960-6d052123403a",
            "identifierKey": "telegram:7933779519",
            "identifierValue": "1033247360",
            "annotations": {
                "name": "Test user"
            }
        }
    },
    "receiver": {
        "connector": {
            "id": "2e63afb0-d4bf-4d2d-a664-0b6152aaab98",
            "identifierValue": "7933779519"
        }
    },
    "body": {
        "type": "text",
        "text": {
            "text": "Reply action 2"
        }
    },
    "meta": {
        "extraInformation": {
            "ChatID": "1033247360"
        }
    },
    "reference": "",
    "parts": [
        {
            "platformReference": "telegram:7933779519:1033247360:172"
        }
    ],
    "status": "delivered",
    "reason": "",
    "direction": "incoming",
    "context": {},
    "chargeableUnits": 1,
    "lastStatusAt": "2024-10-04T12:17:19.16Z",
    "createdAt": "2024-10-04T12:17:19.062Z",
    "updatedAt": "2024-10-04T12:17:19.16Z",
    "batchId": null
}

Interactive message postback

{
    "results": [
        {
            "id": "d11a2b3f-824a-11ef-8327-0a58a9feac02",
            "type": "clicked",
            "createdAt": "2024-10-04T12:18:51.911864444Z",
            "messageId": "c91c618f-2d2c-46d5-8d7e-647cdfc80dd7",
            "channelId": "f007c3cb-1663-5a56-8c91-486056fef49e",
            "platformId": "telegram",
            "messageReference": "telegram:7933779519:1033247360:174",
            "messagePartsCount": 1,
            "receiver": {
                "contacts": [
                    {
                        "id": "00000000-0000-0000-0000-000000000000",
                        "identifierKey": "",
                        "identifierValue": "7933779519",
                        "platformAddress": "7933779519"
                    }
                ]
            },
            "details": "item_1_clicked",
            "metadata": {
                "button": {
                    "payload": "postback-payload-2"
                }
            }
        }
    ]
}