Sendcloud template

The Sendcloud Custom Action connects your Agent to Sendcloud so it can retrieve order and shipment information and use it when answering customer questions. This setup includes:

A predefined OpenAPI schema for Sendcloud
Basic authentication
The required Sendcloud API BaseURL
A health check configuration

After setting up the Action, you can validate it, activate it, and test it in the Playground.

Set up the action

Go to Actions in Watermelon.
In the Actions catalog, click Custom action.
Click Create new Action.
Fill in the fields below.

General details

Action name
Sendcloud Order status Retrieval Description
This action lets you get status information from your orders and use it in your chatbot when customers ask for it. BaseURL
https://panel.sendcloud.sc/api/v2

Authentication

For Authorization Header, select Basic. Username
public_key Replace this with your Sendcloud public key. Password
secret_key Replace this with your Sendcloud secret key.

Health check

Health check URL
https://www.yourdomain.com/health_check Replace this URL with the health check endpoint you want Watermelon to use. Instruction

You should respond with the following message or a similar variation: Sorry, something went wrong on our end. Can I assist you with anything else? Please let me know how I can help.

Schema

Paste the Sendcloud schema into the Schema field:

openapi: 3.0.0
info:
  title: Sendcloud Parcel and Order Tracking API
  description: API for retrieving detailed tracking information of parcels and orders
  version: 1.0.0
servers:
  - url: https://api.sendcloud.com/v1
    description: Sendcloud API server
paths:
  /tracking/{tracking_number}:
    get:
      summary: Retrieve tracking information of a parcel
      description: |
        This endpoint retrieves detailed tracking information of a parcel based on the provided tracking number.
        It returns information such as the unique parcel ID, carrier details, delivery status, and tracking URLs.
        This data can be used by customers to track the status of their parcel delivery.
      parameters:
        - in: path
          name: tracking_number
          description: The tracking number associated with the parcel
          required: true
          schema:
            type: string
      responses:
        '200':
          description: |
            Successful response. Returns detailed tracking information of the parcel.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParcelResponse'
        '404':
          description: Not Found
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
  /orders/:
    get:
      summary: Retrieve order information by order number
      description: |
        This endpoint retrieves detailed order information based on the provided order number.
        It returns data such as order details, payment status, shipping address, and other relevant information.
      parameters:
        - in: query
          name: order_number
          description: The unique order number of the order
          required: true
          schema:
            type: string
      responses:
        '200':
          description: |
            Successful response. Returns detailed information of the order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'


components:
  schemas:
    ParcelResponse:
      type: object
      properties:
        parcel_id:
          type: string
          description: Unique ID for the parcel
        carrier_code:
          type: string
          description: A carrier represented by a Sendcloud code
          example: postnl
        created_at:
          type: string
          format: date-time
          description: |
            Timestamp in ISO format indicating when the parcel was first tracked by Sendcloud’s systems
          example: "2022-01-25T14:42:03.277703+00:00"
        carrier_tracking_url:
          type: string
          description: Link to the carrier’s Tracking page for this parcel
          example: "https://tracking.sendcloud.sc/forward?carrier=postnl&code=3SYZXG132912330&destination=NL&lang=en-us&source=NL&type=parcel&verification=5611+EM&servicepoint_verification=&created_at=2022-01-25"
        sendcloud_tracking_url:
          type: string
          description: Link to Sendcloud’s Tracking page for this parcel
          example: "https://my-bakery.shipping-portal.com/tracking/?country=nl&tracking_number=3SYZXG132912330&postal_code=5611+EM"
        is_return:
          type: boolean
          description: |
            Indicates whether this parcel is a return (incoming) shipment to the merchant
          example: false
        is_to_service_point:
          type: boolean
          description: |
            Indicates whether this parcel is delivered to a service point
          example: false
        is_mail_box:
          type: boolean
          description: |
            Indicates whether this parcel will be delivered to a mail box
          example: false
        expected_delivery_date:
          type: string
          format: date
          description: |
            Date when the parcel is expected to be delivered (estimate, no timestamp)
          example: "2022-01-26"
        statuses:
          type: array
          description: List of shipping statuses for the parcel
          items:
            $ref: '#/components/schemas/ParcelStatus'
    ParcelStatus:
      type: object
      properties:
        carrier_update_timestamp:
          type: string
          format: date-time
          description: |
            Timestamp (ISO format) indicating when the carrier moved the parcel to this status
          example: "2022-01-25T16:42:03.277703+00:00"
        parcel_status_history_id:
          type: string
          description: ID of the historical status
          example: "1270787363"
        parent_status:
          type: string
          description: Current delivery status of the parcel
          example: delivered
        carrier_code:
          type: string
          description: A carrier represented by a Sendcloud code
          example: postnl
        carrier_message:
          type: string
          description: |
            Status description specified by the carrier, more detailed than parent_status
          example: Shipment delivered, no signature
    OrderResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the order
        order_number:
          type: string
          description: Unique order number
        created_at:
          type: string
          format: date-time
          description: Timestamp when the order was created
        modified_at:
          type: string
          format: date-time
          description: Timestamp when the order was last modified
        order_details:
          $ref: '#/components/schemas/FlatOrderDetails'
        payment_details:
          $ref: '#/components/schemas/FlatPaymentDetails'
        customs_details:
          $ref: '#/components/schemas/FlatCustomsDetails'
        shipping_address:
          $ref: '#/components/schemas/ShippingAddress'
    FlatOrderDetails:
      type: object
      properties:
        integration_id:
          type: integer
        status_code:
          type: string
        status_message:
          type: string
        order_created_at:
          type: string
          format: date-time
        order_updated_at:
          type: string
          format: date-time
        order_items:
          type: array
          items:
            $ref: '#/components/schemas/FlatOrderItem'
    FlatOrderItem:
      type: object
      properties:
        name:
          type: string
        weight_value:
          type: number
        weight_unit:
          type: string
        quantity:
          type: integer
        unit_price_value:
          type: number
        unit_price_currency:
          type: string
        total_price_value:
          type: number
        total_price_currency:
          type: string
        delivery_handover_at:
          type: string
          format: date-time
        delivery_deliver_at:
          type: string
          format: date-time
    FlatPaymentDetails:
      type: object
      properties:
        is_cash_on_delivery:
          type: boolean
        total_price_value:
          type: number
        total_price_currency:
          type: string
        status_code:
          type: string
        status_message:
          type: string
        discount_value:
          type: string
        discount_currency:
          type: string
        insurance_value:
          type: string
        insurance_currency:
          type: string
        freight_value:
          type: string
        freight_currency:
          type: string
        other_value:
          type: string
        other_currency:
          type: string
    FlatCustomsDetails:
      type: object
      properties:
        commercial_invoice_number:
          type: string
        shipment_type:
          type: string
    ShippingAddress:
      type: object
      properties:
        name:
          type: string
        address_line_1:
          type: string
        house_number:
          type: string
        postal_code:
          type: string
        city:
          type: string
        country_code:
          type: string
    ErrorResponse:
      type: object
      properties:
        Error:
          type: object
          properties:
            Code:
              type: string
              description: Error code indicating the type of error
              example: NoSuchKey
            Message:
              type: string
              description: Detailed error message describing the issue
              example: The specified key does not exist.
            Key:
              type: string
              description: Key associated with the error, if applicable
              example: v2/103/AHDJ290827.json
            RequestId:
              type: string
              description: ID of the request associated with the error
              example: D4W06G972XFZYM6
            HostId:
              type: string
              description: ID of the host associated with the error
              example: icweEyuSLyXQoikNKR5ndkrbCZL55s7NbFIYbLn25OQqKn1REF1RE5YOUd7XHRUlDSWzOY=
    RateLimitErrorResponse:
      type: object
      properties:
        status:
          type: integer
        message:
          type: string

Click Validate to check the schema.

Example in Watermelon

When everything is configured correctly, click Save and then Activate. Finally, test the Action in the Playground to make sure your Agent can retrieve the expected information from Sendcloud.

Editing an Action Template

After setting up an Action, you can adjust it to your use case. For example, you can add endpoints to the schema, change parameters, or update the name and description. Be careful when changing authentication settings or existing endpoints, as this can prevent the Action from connecting to the API.

Troubleshooting

Issue	Likely cause	What to check
Validation failed	Invalid OpenAPI schema	Check the schema for missing or unsupported fields.
401 Unauthorized	Incorrect Sendcloud credentials	Check your public key and secret key.
404 Not Found	Incorrect endpoint	Check the BaseURL and endpoint path.
Action does not return the expected data	Schema or parameter mismatch	Check the endpoint parameters and API response structure.
Health check fails	Health check endpoint cannot be reached	Check the Health check URL and authentication.

Get started

Build your agent

Publish your agent

Inbox

Contact management

Analytics

Integrations

Guides

Plans & pricing

Resources

Developer resources

Trust & privacy

Set up the action

General details

Authentication

Health check

Schema

Example in Watermelon

Editing an Action Template

Troubleshooting

​Set up the action

​General details

​Authentication

​Health check

​Schema

​Example in Watermelon

​Editing an Action Template

​Troubleshooting

Set up the action

General details

Authentication

Health check

Schema

Example in Watermelon

Editing an Action Template

Troubleshooting