openapi: 3.2.0 info: version: '2022-08-01' title: SMS Messaging Messages API description: Messages servers: [] tags: - name: messages description: Messages paths: /messages: get: summary: Gets messages responses: '200': content: application/json: example: pagination: prev_url: /sms/2022-08-01/messages?page= series: - '1' in: 3 scaffold_url: /sms/2022-08-01/messages?page=__pagy_page__ from: 1 last_url: /sms/2022-08-01/messages?page=1 pages: 1 count: 3 last: 1 first_url: /sms/2022-08-01/messages?page=1 items: 10 next: null next_url: /sms/2022-08-01/messages?page= to: 3 prev: null page: 1 page_url: /sms/2022-08-01/messages?page=1 messages: - direction: out from: '+18885550100' uuid: dcb45297-52ca-4c0c-bfe1-02c6b3589f19 delivery_reports: [] text: Your appointment is confirmed for Friday. Thank you. created_at: '2023-03-23T18:06:05.667Z' to: '+18885550101' cuid: 2281-762B811F1A54 deleted_at: null - direction: out from: '+18885550100' uuid: 392d8bad-08bd-4fe7-8d44-70be4c183edc delivery_reports: [] text: Your appointment is confirmed for Friday. Thank you. created_at: '2023-03-23T18:06:06.667Z' to: '+18885550101' cuid: 7283-4E2BB16F1C54 deleted_at: null - direction: out from: '+18885550100' uuid: c14b1c34-9fb0-4858-8b42-a88a46a809ef delivery_reports: [] text: Your appointment is confirmed for Friday. Thank you. created_at: '2023-03-23T18:06:07.667Z' to: '+18885550101' cuid: D20E-912BB10F1154 deleted_at: null schema: type: object properties: pagination: type: object properties: prev_url: type: string series: items: type: string type: array in: type: integer scaffold_url: type: string from: type: integer last_url: type: string pages: type: integer count: type: integer last: type: integer first_url: type: string items: type: integer next: type: - integer - 'null' next_url: type: string to: type: integer prev: {} page: type: integer page_url: type: string messages: items: type: object properties: direction: type: string from: type: string uuid: type: string delivery_reports: items: {} type: array text: type: string created_at: type: string to: type: string cuid: type: string deleted_at: {} type: array description: returns a list of records sorted in desc created_at order tags: - messages post: requestBody: content: application/json: example: - to: - '+18885550100' from: '+18885550101' text: Your appointment is confirmed for Friday. Thank you. schema: items: $ref: '#/components/schemas/MessageRequest' type: array summary: Creates a message responses: '404': content: application/json: example: message: Not Found - The request could not be completed due to the requested object identifier being unknown to SMS Messaging. schema: type: object properties: message: type: string description: is expected to be not found '409': content: application/json: example: message: Conflict - The request could not be completed due to a conflict with the current state of SMS Messaging. schema: type: object properties: message: type: string description: responds with a conflict '202': content: application/json: example: pagination: prev_url: /sms/2022-08-01/messages?page= series: - '1' in: 1 scaffold_url: /sms/2022-08-01/messages?page=__pagy_page__ from: 1 last_url: /sms/2022-08-01/messages?page=1 pages: 1 count: 1 last: 1 first_url: /sms/2022-08-01/messages?page=1 items: 10 next: null next_url: /sms/2022-08-01/messages?page= to: 1 prev: null page: 1 page_url: /sms/2022-08-01/messages?page=1 messages: - direction: out from: '+18885550101' uuid: 1aef6c85-10bc-4de8-8002-02e8d5b2235f delivery_reports: [] text: Your appointment is confirmed for Friday. Thank you. created_at: '2022-01-31T23:50:00.000Z' to: '+18885550100' cuid: 3E83-592C1B19171B deleted_at: null schema: type: object properties: pagination: type: object properties: prev_url: type: string series: items: type: string type: array in: type: integer scaffold_url: type: string from: type: integer last_url: type: string pages: type: integer count: type: integer last: type: integer first_url: type: string items: type: integer next: {} next_url: type: string to: type: integer prev: {} page: type: integer page_url: type: string messages: items: type: object properties: direction: type: string from: type: string uuid: type: string delivery_reports: items: {} type: array text: type: string created_at: type: string to: type: string cuid: type: string deleted_at: {} type: array description: creates a message and forwards to kafka '400': content: application/json: example: message: Problems parsing JSON schema: type: object properties: message: type: string description: is expected to be bad request tags: - messages /messages/phone_number/{phone_number}: get: summary: Gets messages by phone number responses: '200': content: application/json: example: pagination: prev_url: /sms/2022-08-01/messages/phone_number/+18885550100?page= series: - '1' in: 1 scaffold_url: /sms/2022-08-01/messages/phone_number/+18885550100?page=__pagy_page__ from: 1 last_url: /sms/2022-08-01/messages/phone_number/+18885550100?page=1 pages: 1 count: 1 last: 1 first_url: /sms/2022-08-01/messages/phone_number/+18885550100?page=1 items: 10 next: null next_url: /sms/2022-08-01/messages/phone_number/+18885550100?page= to: 1 prev: null page: 1 page_url: /sms/2022-08-01/messages/phone_number/+18885550100?page=1 messages: - direction: out from: '+18885550100' uuid: 1554d3d0-17c9-4752-82ad-f19394eac6a3 delivery_reports: [] text: Your appointment is confirmed for Friday. Thank you. created_at: '2023-03-23T18:05:57.442Z' to: '+18885550101' cuid: 926F-272B71DF1D54 deleted_at: null schema: type: object properties: pagination: type: object properties: prev_url: type: string series: items: type: string type: array in: type: integer scaffold_url: type: string from: type: integer last_url: type: string pages: type: integer count: type: integer last: type: integer first_url: type: string items: type: integer next: {} next_url: type: string to: type: integer prev: {} page: type: integer page_url: type: string messages: items: type: object properties: direction: type: string from: type: string uuid: type: string delivery_reports: items: {} type: array text: type: string created_at: type: string to: type: string cuid: type: string deleted_at: {} type: array description: returns the expected response columns '404': content: application/json: example: message: Not Found - Could not find any messages for the requested phone number schema: type: object properties: message: type: string description: returns a helpful phone number not_found error parameters: - $ref: '#/components/parameters/phone_number' tags: - messages /messages/phone_number/{phone_number}/usage: get: summary: Gets message usage information by phone number responses: '200': content: application/json: example: messages: phone_number: '+18885550100' outgoing: segments: 0 messages: 0 incoming: segments: 0 messages: 0 schema: type: object properties: messages: type: object properties: phone_number: type: string outgoing: type: object properties: segments: type: integer messages: type: integer incoming: type: object properties: segments: type: integer messages: type: integer description: returns 0 segments and messages '404': content: application/json: example: message: Not Found - the requested phone number, +18885550100, is not in the system schema: type: object properties: message: type: string description: returns 0 segments and messages parameters: - $ref: '#/components/parameters/phone_number' tags: - messages /messages/uuid/{message_uuid}: delete: summary: Deletes a message by message id responses: '200': content: application/json: example: message: direction: out from: '+18885550100' uuid: dc9e113c-914a-4b64-9d19-f8010ab59f5b delivery_reports: - progress_bit: 1 created_at: '2022-07-22T04:01:01.000Z' uuid: ed4afb09-1f06-401c-bf1b-d0fe65f1627d text: Your appointment is confirmed for Friday. Thank you. segments: 1 failed_at: null to: '+18885550101' cuid: 9E6C-0648D44DECF7 delivered_at: null carrier_message_id: null deleted_at: '2022-07-24T04:01:01.000Z' created_at: '2022-07-22T04:01:01.000Z' virtual_line_id: 146 schema: type: object properties: message: type: object properties: direction: type: string from: type: string uuid: type: string delivery_reports: items: type: object properties: progress_bit: type: integer created_at: type: string uuid: type: string type: array text: type: string segments: type: integer failed_at: {} to: type: string cuid: type: string delivered_at: {} carrier_message_id: {} deleted_at: type: string created_at: type: string virtual_line_id: type: integer description: deletes the message and returns a json hash with the expected format and fields parameters: - $ref: '#/components/parameters/message_uuid' tags: - messages get: summary: Gets a message given its message id responses: '200': content: application/json: example: message: direction: out from: '+18885550100' uuid: 123e4567-e89b-12d3-a456-426655440000 delivery_reports: - progress_bit: 1 created_at: '2022-09-22T04:01:01.000Z' uuid: aa1f8026-8b81-446e-af53-1ede594b8c7c text: Your appointment is confirmed for Friday. Thank you. segments: 1 failed_at: null to: '+18885550101' cuid: 2215-642B016F1D54 delivered_at: '2022-09-22T04:01:01.000Z' carrier_message_id: '456' deleted_at: null created_at: '2022-09-22T04:01:01.000Z' virtual_line_id: 112 schema: type: object properties: message: type: object properties: direction: type: string from: type: string uuid: type: string delivery_reports: items: type: object properties: progress_bit: type: integer created_at: type: string uuid: type: string type: array text: type: string segments: type: integer failed_at: {} to: type: string cuid: type: string delivered_at: type: string carrier_message_id: type: string deleted_at: {} created_at: type: string virtual_line_id: type: integer description: returns the found message, with the expected format and fields '404': content: application/json: example: message: Not Found - Could not find any messages for the requested uuid schema: type: object properties: message: type: string description: returns an appropriate error parameters: - $ref: '#/components/parameters/message_uuid' tags: - messages /messages/uuid/{message_uuid}/delivery_reports: get: summary: Gets delivery reports for a given message id responses: '200': content: application/json: example: delivery_reports: - progress_bit: 1 created_at: '2022-07-22T04:01:01.000Z' uuid: 0536c12f-7399-4786-8682-bce652e75655 - progress_bit: 1 created_at: '2022-07-22T04:01:02.000Z' uuid: eccd15a4-7697-4115-afd6-a6dafbf66408 - progress_bit: 1 created_at: '2022-07-22T04:01:03.000Z' uuid: 90f8f107-7e6d-4681-b419-b1f1c6dc9064 - progress_bit: 1 created_at: '2022-07-22T04:01:04.000Z' uuid: 4e62e2e1-c432-47b0-9f6e-a72d34e6bb41 - progress_bit: 1 created_at: '2022-07-22T04:01:05.000Z' uuid: fa6ca0ec-f3ac-48a3-8b07-554dfae2bb70 - progress_bit: 1 created_at: '2022-07-22T04:01:06.000Z' uuid: e452254c-8b39-47a8-8d6f-d8302bda3582 - progress_bit: 1 created_at: '2022-07-22T04:01:07.000Z' uuid: c3e4b5d9-9a42-4223-86a8-a1d20f1c5665 - progress_bit: 1 created_at: '2022-07-22T04:01:08.000Z' uuid: 45082fbd-e9fd-44c1-94cc-c542b8b98253 - progress_bit: 1 created_at: '2022-07-22T04:01:09.000Z' uuid: 3508cac2-a48f-45eb-a66f-0b37b614783b - progress_bit: 1 created_at: '2022-07-22T04:01:10.000Z' uuid: 288bfcaa-ecb3-498e-88d1-8086f747ded1 pagination: prev_url: /sms/2022-08-01/messages/uuid/f4d68382-1652-4b4f-8bdb-13c39bb5cdae/delivery_reports?page= series: - '1' - 2 in: 10 scaffold_url: /sms/2022-08-01/messages/uuid/f4d68382-1652-4b4f-8bdb-13c39bb5cdae/delivery_reports?page=__pagy_page__ from: 1 last_url: /sms/2022-08-01/messages/uuid/f4d68382-1652-4b4f-8bdb-13c39bb5cdae/delivery_reports?page=2 pages: 2 count: 18 last: 2 first_url: /sms/2022-08-01/messages/uuid/f4d68382-1652-4b4f-8bdb-13c39bb5cdae/delivery_reports?page=1 items: 10 next: 2 next_url: /sms/2022-08-01/messages/uuid/f4d68382-1652-4b4f-8bdb-13c39bb5cdae/delivery_reports?page=2 to: 10 prev: null page: 1 page_url: /sms/2022-08-01/messages/uuid/f4d68382-1652-4b4f-8bdb-13c39bb5cdae/delivery_reports?page=1 schema: type: object properties: delivery_reports: items: type: object properties: progress_bit: type: integer created_at: type: string uuid: type: string type: array pagination: type: object properties: prev_url: type: string series: items: type: string type: array in: type: integer scaffold_url: type: string from: type: integer last_url: type: string pages: type: integer count: type: integer last: type: integer first_url: type: string items: type: integer next: type: integer next_url: type: string to: type: integer prev: {} page: type: integer page_url: type: string description: returns the sorted created_at:asc, paginated records '422': content: application/json: example: message: 'The request contains unsupported sort columns: ''destination''. Supported columns: ''created_at, progress_bit''' schema: type: object properties: message: type: string description: returns a helpful error message '404': content: application/json: example: message: Not Found - Could not find any messages for the requested uuid schema: type: object properties: message: type: string description: returns an appropriate error parameters: - $ref: '#/components/parameters/message_uuid' tags: - messages /messages/uuid/{message_uuid}/delivery_reports/uuid/{delivery_report_uuid}: get: summary: Gets messages by message id and delivery report id responses: '200': content: application/json: example: delivery_report: uuid: 8c0bfc00-e120-48d8-a6da-f7319e625583 message_uuid: 007bd98c-2a7b-4df5-ab52-f2d05d88151f progress_bit: 1 created_at: '2022-07-22T04:01:01.000Z' destination: '+18885550101' carrier_description: null carrier_errorcode: null schema: type: object properties: delivery_report: type: object properties: uuid: type: string message_uuid: type: string progress_bit: type: integer created_at: type: string destination: type: string carrier_description: {} carrier_errorcode: {} description: returns the found delivery report, with the expected format and fields '404': content: application/json: example: message: Not Found - Could not find any delivery reports for the requested delivery report uuid schema: type: object properties: message: type: string description: returns an appropriate error parameters: - $ref: '#/components/parameters/message_uuid' - $ref: '#/components/parameters/delivery_report_uuid' tags: - messages components: parameters: phone_number: schema: type: string description: The Phone Number in E.164 Format in: path required: true example: '+18885550100' name: phone_number message_uuid: schema: type: string description: The Message UUID in: path required: true example: da8ec5c7-bd73-4b35-9afb-b56050fd6568 name: message_uuid delivery_report_uuid: schema: type: string description: The Delivery Report UUID in: path required: true example: 1162b7e8-e7b1-493b-b8c4-0bc838161c5f name: delivery_report_uuid schemas: MessageRequest: type: object properties: to: items: type: string type: array from: type: string text: type: string